idnits 2.17.1 draft-trammell-mplane-protocol-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. -- The document has examples using IPv4 documentation addresses according to RFC6890, but does not use any IPv6 documentation addresses. Maybe there should be IPv6 examples, too? ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 1646: '...ession protocol for mPlane, it MUST be...' RFC 2119 keyword, line 1648: '... servers MUST present certificates f...' RFC 2119 keyword, line 1649: '...Plane Components MUST use the certific...' RFC 2119 keyword, line 1651: '...horized to invoke. mPlane Clients MUST...' RFC 2119 keyword, line 1653: '...ne Clients and Components MUST NOT use...' (2 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 27, 2016) is 2735 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Unused Reference: 'RFC3205' is defined on line 1957, but no explicit reference was found in the text == Unused Reference: 'RFC7230' is defined on line 1998, but no explicit reference was found in the text -- Obsolete informational reference (is this intentional?): RFC 3205 (Obsoleted by RFC 9205) -- Obsolete informational reference (is this intentional?): RFC 5246 (Obsoleted by RFC 8446) -- Obsolete informational reference (is this intentional?): RFC 7159 (Obsoleted by RFC 8259) -- Obsolete informational reference (is this intentional?): RFC 7230 (Obsoleted by RFC 9110, RFC 9112) Summary: 1 error (**), 0 flaws (~~), 4 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group B. Trammell, Ed. 3 Internet-Draft M. Kuehlewind, Ed. 4 Intended status: Informational ETH Zurich 5 Expires: April 30, 2017 October 27, 2016 7 mPlane Protocol Specification 8 draft-trammell-mplane-protocol-02 10 Abstract 12 This document defines the mPlane protocol for coordination of 13 heterogeneous network measurement Components: probes and repositories 14 that measure, analyze, and store network measurements, data derived 15 from measurements, and other ancillary data about elements of the 16 network. The mPlane architecture is defined in terms of 17 relationships between Components and Clients which communicate using 18 the mPlane protocol defined in this document. 20 This revision of the document describes Version 2 of the mPlane 21 protocol. 23 Status of This Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at http://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on April 30, 2017. 40 Copyright Notice 42 Copyright (c) 2016 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (http://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 58 1.1. Changes from Revision -00 (Protocol version 1) . . . . . 4 59 1.2. Changes from Revision -01 . . . . . . . . . . . . . . . . 4 60 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 61 3. Overview of the mPlane Architecture . . . . . . . . . . . . . 5 62 3.1. Key Architectural Principles and Features . . . . . . . . 6 63 3.1.1. Flexibility and Extensibility . . . . . . . . . . . . 6 64 3.1.2. Schema-centric Measurement Definition . . . . . . . . 7 65 3.1.3. Iterative Measurement Support . . . . . . . . . . . . 7 66 3.1.4. Weak Imperativeness . . . . . . . . . . . . . . . . . 7 67 3.2. Entities and Relationships . . . . . . . . . . . . . . . 8 68 3.2.1. Components and Clients . . . . . . . . . . . . . . . 9 69 3.2.2. Probes and Repositories . . . . . . . . . . . . . . . 9 70 3.3. Message Types and Message Exchange Sequences . . . . . . 9 71 3.4. Integrating Measurement Tools into mPlane . . . . . . . . 11 72 3.5. From Architecture to Protocol Specification . . . . . . . 11 73 4. Protocol Information Model . . . . . . . . . . . . . . . . . 11 74 4.1. Element Registry . . . . . . . . . . . . . . . . . . . . 12 75 4.1.1. Structured Element Names . . . . . . . . . . . . . . 13 76 4.1.2. Primitive Types . . . . . . . . . . . . . . . . . . . 14 77 4.1.3. Augmented Registry Information . . . . . . . . . . . 15 78 4.2. Message Types . . . . . . . . . . . . . . . . . . . . . . 15 79 4.2.1. Capability and Withdrawal . . . . . . . . . . . . . . 16 80 4.2.2. Specification and Interrupt . . . . . . . . . . . . . 16 81 4.2.3. Result . . . . . . . . . . . . . . . . . . . . . . . 16 82 4.2.4. Receipt and Redemption . . . . . . . . . . . . . . . 16 83 4.2.5. Exception . . . . . . . . . . . . . . . . . . . . . . 17 84 4.2.6. Envelope . . . . . . . . . . . . . . . . . . . . . . 17 85 4.3. Message Sections . . . . . . . . . . . . . . . . . . . . 18 86 4.3.1. Message Type and Verb . . . . . . . . . . . . . . . . 19 87 4.3.2. Version . . . . . . . . . . . . . . . . . . . . . . . 20 88 4.3.3. Registry . . . . . . . . . . . . . . . . . . . . . . 20 89 4.3.4. Label . . . . . . . . . . . . . . . . . . . . . . . . 20 90 4.3.5. Temporal Scope (When) . . . . . . . . . . . . . . . . 21 91 4.3.6. Parameters . . . . . . . . . . . . . . . . . . . . . 22 92 4.3.7. Metadata . . . . . . . . . . . . . . . . . . . . . . 23 93 4.3.8. Result Columns and Values . . . . . . . . . . . . . . 24 94 4.3.9. Export . . . . . . . . . . . . . . . . . . . . . . . 24 95 4.3.10. Link . . . . . . . . . . . . . . . . . . . . . . . . 25 96 4.3.11. Token . . . . . . . . . . . . . . . . . . . . . . . . 25 97 4.3.12. Contents . . . . . . . . . . . . . . . . . . . . . . 26 98 4.4. Message Uniqueness and Idempotence . . . . . . . . . . . 26 99 4.4.1. Message Schema . . . . . . . . . . . . . . . . . . . 26 100 4.4.2. Message Identity . . . . . . . . . . . . . . . . . . 27 101 4.5. Designing Measurement and Repository Schemas . . . . . . 27 102 5. Representations and Session Protocols . . . . . . . . . . . . 28 103 5.1. JSON representation . . . . . . . . . . . . . . . . . . . 28 104 5.1.1. Textual representations of element values . . . . . . 29 105 5.1.2. Example mPlane Capabilities and Specifications in 106 JSON . . . . . . . . . . . . . . . . . . . . . . . . 30 107 5.2. mPlane over WebSockets over TLS . . . . . . . . . . . . . 36 108 5.2.1. mPlane PKI for WebSockets . . . . . . . . . . . . . . 37 109 5.2.2. Capability Advertisement for WebSockets . . . . . . . 37 110 5.2.3. mPlane Link and Export URLs for WebSockets . . . . . 37 111 6. Deployment Considerations . . . . . . . . . . . . . . . . . . 38 112 6.1. Supervisors and Federation . . . . . . . . . . . . . . . 38 113 6.1.1. Component Registration . . . . . . . . . . . . . . . 40 114 6.1.2. Client Authentication . . . . . . . . . . . . . . . . 40 115 6.1.3. Capability Composition and Specification 116 Decomposition . . . . . . . . . . . . . . . . . . . . 40 117 6.2. Indirect Export . . . . . . . . . . . . . . . . . . . . . 40 118 6.3. Error Handling in mPlane Workflows . . . . . . . . . . . 41 119 7. Security Considerations . . . . . . . . . . . . . . . . . . . 42 120 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 42 121 9. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 42 122 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 43 123 11. Informative References . . . . . . . . . . . . . . . . . . . 43 124 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 44 126 1. Introduction 128 This document describes the mPlane architecture and protocol, which 129 is designed to provide control and coordination of heterogeneous 130 network measurement tools. It is based heavily on the mPlane 131 project's deliverable 1.4 [D14], and is submitted for the information 132 of the Internet engineering community. Section 3 gives an overview 133 of the mPlane architecture, Section 4 defines the protocol 134 information model, and Section 5 defines the representations of this 135 data model and session protocols over which mPlane is supported. 137 Present work is focused on mPlane represented in JSON using 138 WebSockets [RFC6455] as a session protocol. 140 This revision of the document describes Version 2 of the mPlane 141 protocol. 143 1.1. Changes from Revision -00 (Protocol version 1) 145 o WebSockets has been added as a session protocol for the mPlane 146 protocol. Message flow has been modified to fit. 148 o Redemptions have been expanded to allow temporally-scoped partial 149 redemption of long-running measurements. 151 o The "object" primitive type has been added to allow structured 152 objects to be represented directly in mPlane messages using the 153 underlying representation. 155 o A number of obsolete features have been deprecated based on 156 implementation and pilot deployment experience, and removed from 157 the protocol description: 159 * HTTPS as a session protocol, as it is a poor fit for mPlane's 160 exchanges 162 * Callback control, as it is no longer needed without the 163 limitations of HTTPS as a session protocol 165 * The Indirection message type, as the same functionality is 166 available for all message types using the link section. 168 * Repeating measurements, as their functionality has been 169 replaced by partial redemption 171 o References to the "core" registry have been removed, as all 172 element registries must in any case be explicitly defined in 173 mPlane Capabilities, Specifications, and Results. An eventual 174 proposed standard mPlane protocol would refer to an IANA-managed 175 core registry. 177 1.2. Changes from Revision -01 179 o Editorial changes only. 181 2. Terminology 183 [EDITOR'S NOTE: these terms are not necessarily capitalized within 184 the document at this time. Fix this.] 186 Client: An entity which implements the mPlane protocol, receives 187 Capabilities published by one or more Components, and sends 188 Specifications to those Component(s) to perform measurements and 189 analysis. See Section 3.2.1. 191 Component: An entity which implements the mPlane protocol specified 192 within this document, advertises its Capabilities and accepts 193 Specifications which request the use of those Capabilities. The 194 measurements, analyses, storage facilities and other services 195 provided by a Component are completely defined by its 196 Capabilities. See Section 3.2.1. 198 mPlane Message: The atomic unit of exchange in the mPlane protocol. 199 The treatment of a message at a Client or Component receiving it 200 is based upon its type; see Section 4.2. 202 Capability: An mPlane message that contains a statement of a 203 Component's ability and willingness to perform a specific 204 operation, conveyed from a Component to a Client. A Capability 205 does not represent a guarantee that the specific operation can or 206 will be performed at a specific point in time. See Section 4.2.1 208 Specification: An mPlane message that contains a statement of a 209 Client's desire that a Component should perform a specific 210 operation, conveyed from a Client to a Component. It can be 211 conceptually viewed as a Capability whose parameters have been 212 filled in with values. See Section 4.2.2. 214 Result: An mPlane message containing a statement produced by a 215 Component that a particular measurement was taken and the given 216 values were observed, or that a particular operation or analysis 217 was performed and a the given values were produced. It can be 218 conceptually viewed as a Specification whose result columns have 219 been filled in with values. See Section 4.2.3. 221 Element: An identifier for a parameter or result column in a 222 Capability, Specification, or Result, binding a name to a 223 primitive type. Elements are contained in registries that contain 224 the vocabulary from which mPlane Capabilities, Specifications, and 225 Results can be built. See Section 4.1. 227 3. Overview of the mPlane Architecture 229 mPlane is built around an architecture in which Components provide 230 network measurement services and access to stored measurement data 231 which they advertise via Capabilities completely describing these 232 services and data. A Client makes use of these Capabilities by 233 sending Specifications that respond to them back to the Components. 234 Components may then either return Results directly to the Clients or 235 sent to some third party via indirect export using an external 236 protocol. The Capabilities, Specifications, and Results are carried 237 over the mPlane protocol, defined in detail in this document. An 238 mPlane measurement infrastructure is built up from these basic 239 blocks. 241 Components can be roughly classified into probes which generate 242 measurement data and repositories which store and analyze measurement 243 data, though the difference between a probe and a repository in the 244 architecture is merely a matter of the Capabilities it provides. 245 Components can be pulled together into an infrastructure by a 246 supervisor (see Section 6.1), which presents a Client interface to 247 subordinate Components and a Component interface to superordinate 248 Clients, aggregating Capabilities into higher-level measurements and 249 distributing Specifications to perform them. 251 The mPlane protocol is, in essence, a self-describing, error- and 252 delay- tolerant remote procedure call (RPC) protocol between Clients 253 and Components: each Capability exposes an entry point in the API 254 provided by the Component; each Specification embodies an API call; 255 and each Result returns the results of an API call. This arrangement 256 is shown in Figure 1 below. 258 +=================================+ 259 | | 260 +-->| Client | 261 | | |<-+ 262 | +=================================+ | 263 | n | | | 264 Capability | Specification Result 265 | | m V | 266 | +=================================+ | 267 | | |--+ 268 +---| Component | 269 | | 270 +=================================+ 272 Figure 1: The simplest form of the mPlane architecture 274 3.1. Key Architectural Principles and Features 276 mPlane differs from a simple RPC facility in several important ways, 277 detailed in the subsections below. 279 3.1.1. Flexibility and Extensibility 281 First, given the heterogeneity of the measurement tools and 282 techniques applied, it is necessary for the protocol to be as 283 flexible and extensible as possible. Therefore, the architecture in 284 its simplest form consists of only two entities and one relationship, 285 as shown in the diagram below: n Clients connect to m Components via 286 the mPlane protocol. Anything which can speak the mPlane protocol 287 and exposes Capabilities thereby is a Component; anything which can 288 understand these Capabilities and send Specifications to invoke them 289 is a Client. Everything a Component can do, from the point of view 290 of mPlane, is entirely described by its Capabilities. Capabilities 291 are even used to expose optional internal features of the protocol 292 itself, and provide a method for built-in protocol extensibility. 294 3.1.2. Schema-centric Measurement Definition 296 Second, given the flexibility required above, the key to measurement 297 interoperability is the comparison of data types. Each Capability, 298 Specification, and Result contains a schema, comprising the set of 299 parameters required to execute a measurement or query and the columns 300 in the data set that results. From the point of view of mPlane, the 301 schema completely describes the measurement. This implies that when 302 exposing a measurement using mPlane, the developer of a Component 303 must build each Capabilities it advertises such that the semantics of 304 the measurement are captured by the set of columns in its schema. 305 The elements from which schemas can be built are captured in a type 306 registry. The mPlane platform provides a core registry for common 307 measurement use cases within the project, and the registry facility 308 is itself fully extensible as well, for supporting new applications 309 without requiring central coordination beyond the domain or set of 310 domains running the application. 312 3.1.3. Iterative Measurement Support 314 Third, the exchange of messages in the protocol was chosen to support 315 iterative measurement in which the aggregated, high-level results of 316 a measurement are used as input to a decision process to select the 317 next measurement. Specifically, the protocol blends control messages 318 (Capabilities and Specifications) and data messages (Results) into a 319 single workflow. 321 3.1.4. Weak Imperativeness 323 Fourth, the mPlane protocol is weakly imperative. A Capability 324 represents a willingness and an ability to perform a given 325 measurement or execute a query, but not a guarantee or a reservation 326 to do so. Likewise, a Specification contains a set of parameters and 327 a temporal scope for a measurement a Client wishes a Component to 328 perform on its behalf, but execution of Specifications is best- 329 effort. A Specification is not an instruction which must Result 330 either in data or in an error. This property arises from our 331 requirement to support large-scale measurement infrastructures with 332 thousands of similar Components, including resource- and 333 connectivity-limited probes such as smartphones and customer-premises 334 equipment (CPE) like home routers. These may be connected to a 335 supervisor only intermittently. In this environment, the operability 336 and conditions in which the probes find themselves may change more 337 rapidly than can be practicably synchronized with a central 338 supervisor; requiring reliable operation would compromise scalability 339 of the architecture. 341 To support weak imperativeness, each message in the mPlane protocol 342 is self- contained, and contains all the information required to 343 understand the message. For instance, a Specification contains the 344 complete information from the Capability which it responds to, and a 345 Result contains its Specification. In essence, this distributes the 346 state of the measurements running in an infrastructure across all 347 Components, and any state resynchronization that is necessary after a 348 disconnect happens implicitly as part of message exchange. The 349 failure of a Component during a large-scale measurement can be 350 detected and corrected after the fact, by examining the totality of 351 the generated data. 353 This distribution of state throughout the measurement infrastructure 354 carries with it a distribution of responsibility: a Component holding 355 a Specification is responsible for ensuring that the measurement or 356 query that the Specification describes is carried out, because the 357 Client or supervisor which has sent the Specification does not 358 necessarily keep any state for it. 360 Error handling in a weakly imperative environment is different to 361 that in traditional RPC protocols. The exception facility provided 362 by mPlane is designed only to report on failures of the handling of 363 the protocol itself. Each Component and Client makes its best effort 364 to interpret and process any authorized, well-formed mPlane protocol 365 message it receives, ignoring those messages which are spurious or no 366 longer relevant. This is in contrast with traditional RPC protocols, 367 where even common exceptional conditions are signaled, and 368 information about missing or otherwise defective data must be 369 correlated from logs about measurement control. This traditional 370 design pattern is not applicable in infrastructures where the 371 supervisor has no control over the functionality and availability of 372 its associated probes. 374 3.2. Entities and Relationships 376 The entities in the mPlane protocol and the relationships among them 377 are described in more detail in the subsections below. 379 3.2.1. Components and Clients 381 Specifically, a Component is any entity which implements the mPlane 382 protocol specified within this document, advertises its Capabilities 383 and accepts Specifications which request the use of those 384 Capabilities. The measurements, analyses, storage facilities and 385 other services provided by a Component are completely defined by its 386 Capabilities. 388 Conversely, a Client is any entity which implements the mPlane 389 protocol, receives Capabilities published by one or more Components, 390 and sends Specifications to those Component(s) to perform 391 measurements and analysis. 393 Every interaction in the mPlane protocol takes place between a 394 Component and a Client. Indeed, the simplest instantiation of the 395 mPlane architecture consists of one or more Clients taking 396 Capabilities from one or more Components, and sending Specifications 397 to invoke those Capabilities, as shown in Figure 1. An mPlane domain 398 may consist of as little as a single Client and a single Component. 399 In this arrangement, mPlane provides a measurement-oriented RPC 400 mechanism. 402 3.2.2. Probes and Repositories 404 Measurement Components can be roughly divided into two categories: 405 probes and repositories. Probes perform measurements, and 406 repositories provide access to stored measurements, analysis of 407 stored measurements, or other access to related external data 408 sources. External databases and data sources (e.g., routing looking 409 glasses, WHOIS services, DNS, etc.) can be made available to mPlane 410 Clients through repositories acting as gateways to these external 411 sources, as well. 413 Note that this categorization is very rough: what a Component can do 414 is completely described by its Capabilities, and some Components may 415 combine properties of both probes and repositories. 417 3.3. Message Types and Message Exchange Sequences 419 The basic messages in the mPlane protocol are Capabilities, 420 Specifications, and Results, as described above. The full protocol 421 contains other message types as well. Withdrawals cancel 422 Capabilities (i.e., indicate that the Component is no longer capable 423 or willing to perform a given measurement) and interrupts cancel 424 Specifications (i.e., indicate that the Component should stop 425 performing the measurement). Receipts can be given in lieu of 426 Results for not-yet completed measurements or queries, and 427 redemptions can be used to retrieve Results referred to by a receipt. 428 Exceptions can be sent by Clients or Components at any time to signal 429 protocol-level errors to their peers. 431 The following sequences of messages are possible within the mPlane 432 protocol: 434 Client Component 435 |<---------- Capability -| ( direct response ) 436 |- Specification ------->| 437 |<-------------- Result -| 438 | | 439 |<---------- Capability -| ( delayed response ) 440 |- Specification ------->| 441 |<------------- Receipt -| 442 | . . . | 443 |- (Redemption) -------->| 444 |<-------------- Result -| 445 | | 446 |<---------- Capability -| ( indirect export ) 447 |- Specification ------->| 448 |<------------- Receipt -| 449 |.... indirect export ...| 450 |- (Interrupt) --------->| 451 | | 452 |<---------- Capability -| ( eventual withdrawal ) 453 | . . . | 454 |<---------- Withdrawal -| 456 Figure 2: Possible sequences of messages in the mPlane protocol 458 In the nominal sequence, a Capability leads to a Specification leads 459 to a Result, where Results may be transmitted by some other protocol. 460 All the paths through the sequence of messages are shown in the 461 diagram above; message types are described in detail in Section 4.2. 463 Separate from the sequence of messages, the mPlane protocol supports 464 two connection establishment patterns: 466 o Client-initiated, in which Clients connect directly to Components 467 at known, stable URLs. Client-initiated workflows are intended 468 for use between Clients and supervisors, for access to 469 repositories, and for access to probes embedded within a network 470 infrastructure. 472 o Component-initiated, in which Components initiate connections to 473 Clients. Component-initiated workflows are intended for use 474 between Components without stable routable addresses and 475 supervisors, e.g. for small probes on embedded devices, mobile 476 devices, or software probes embedded in browsers on personal 477 computers behind network-address translators (NATs) or firewalls 478 which prevent a Client from establishing a connection to them. 480 Within a given mPlane domain, these patterns can be combined (along 481 with indirect export and direct access) to facilitate complex 482 interactions among Clients and Components according to the 483 requirements imposed by the application and the deployment of 484 Components in the network. 486 3.4. Integrating Measurement Tools into mPlane 488 mPlane's flexibility and the self-description of measurements 489 provided by the Capability-Specification-Result cycle was designed to 490 allow a wide variety of existing measurement tools, both probes and 491 repositories, to be integrated into an mPlane domain. In both cases, 492 the key to integration is to define a Capability for each of the 493 measurements the tool can perform or the queries the repository needs 494 to make available within an mPlane domain. Each Capability has a set 495 of parameters - information required to run the measurement or the 496 query - and a set of result columns - information which the 497 measurement or query returns. 499 The parameters and result columns make up the measurement's schema, 500 and are chosen from an extensible registry of elements. Practical 501 details are given in Section 4.5. 503 3.5. From Architecture to Protocol Specification 505 The remainder of this document builds the protocol Specification 506 based on this architecture from the bottom up. First, we define the 507 protocol's information model from the element registry through the 508 types of mPlane messages and the sections they are composed of. We 509 then define a concrete representation of this information model using 510 Javascript Object Notation (JSON, [RFC7159]), and define bindings to 511 WebSockets [RFC6455]} over TLS as a session protocol. 513 4. Protocol Information Model 515 The mPlane protocol is message-oriented, built on the representation- 516 and session-protocol-independent exchange of messages between Clients 517 and Components. This section describes the information model, 518 starting from the element registry which defines the elements from 519 which Capabilities can be built, then detailing each type of message, 520 and the sections that make these messages up. It then provides 521 advice on using the information model to model measurements and 522 queries. 524 4.1. Element Registry 526 An element registry makes up the vocabulary by which mPlane 527 Components and Clients can express the meaning of parameters, 528 metadata, and result columns for mPlane statements. A registry is 529 represented as a JSON [RFC7159] object with the following keys: 531 o registry-format: currently "mplane-0", determines the supported 532 features of the registry format. 534 o registry-uri: the URI identifying the registry. The URI must be 535 dereferencable to retrieve the canonical version of this registry. 537 o registry-revision: a serial number starting with 0 and incremented 538 with each revision to the content of the registry. 540 o includes: a list of URLs to retrieve additional registries from. 541 Included registries will be evaluated in depth-first order, and 542 elements with identical names will be replaced by registries 543 parsed later. 545 o elements: a list of objects, each of which has the following three 546 keys: 548 * name: The name of the element. 550 o prim: The name of the primitive type of the element, from the list 551 of primitives in Section 4.1.2. 553 * desc: An English-language description of the meaning of the 554 element. 556 Since the element names will be used as keys in mPlane messages, 557 mPlane binds to JSON, and JSON mandates lowercase key names, element 558 names must use only lowercase letters. 560 An example registry with two elements and no includes follows: 562 { "registry-format": "mplane-0", 563 "registry-uri", "https://example.com/mplane/registry/core", 564 "registry-revision": 0, 565 "includes": [], 566 "elements": [ 567 { "name": "full.structured.name", 568 "prim": "string", 569 "desc": "A representation of foo..." 570 }, 571 { "name": "another.structured.name", 572 "prim": "string", 573 "desc": "A representation of bar..." 574 }, 575 ] 576 } 578 Fully qualified element names consist of the element's name as an 579 anchor after the URI from which the element came, e.g. 580 "https://example.com/mplane/registry/core#full.structured.name". 581 Elements within the type registry are considered globally equal based 582 on their fully qualified names. However, within a given mPlane 583 message, elements are considered equal based on unqualified names. 585 4.1.1. Structured Element Names 587 To ease understanding of mPlane type registries, element names are 588 structured by convention; that is, an element name is made up of the 589 following structural parts in order, separated by the dot ('.') 590 character: 592 o basename: exactly one, the name of the property the element 593 specifies or measures. All elements with the same basename 594 describe the same basic property. For example, all elements with 595 basename '"source"' relate to the source of a packet, flow, active 596 measurement, etc.; and elements with basename '"delay"'' relate to 597 the measured delay of an operation. 599 o modifier: zero or more, additional information differentiating 600 elements with the same basename from each other. Modifiers may 601 associate the element with a protocol layer, or a particular 602 variety of the property named in the basename. All elements with 603 the same basename and modifiers refer to exactly the same 604 property. Examples for the "delay" basename include "oneway" and 605 "twoway", differentiating whether a delay refers to the path from 606 the source to the destination or from the source to the source via 607 the destination; and "icmp" and "tcp", describing the protocol 608 used to measure the delay. 610 o units: zero or one, present if the quantity can be measured in 611 different units. 613 o aggregation: zero or one, if the property is a metric derived from 614 multiple singleton measurements. Supported aggregations are: 616 * "min": minimum value 618 * "max": maximum value 620 * "mean": mean value 622 * "sum": sum of values 624 * "NNpct" (where NN is a two-digit number 01-99): percentile 626 * "median": shorthand for and equivalent to "50pct". 628 * "count": count of values aggregated 630 When mapping mPlane structured names into contexts in which dots have 631 special meaning (e.g. SQL column names or variable names in many 632 programming languages), the dots may be replaced by underscores 633 ('_'). When using external type registries (e.g. the IPFIX 634 Information Element Registry), element names are not necessarily 635 structured. 637 4.1.2. Primitive Types 639 The mPlane protocol supports the following primitive types for 640 elements in the type registry: 642 o string: a sequence of Unicode characters 644 o natural: an unsigned integer 646 o real: a real (floating-point) number 648 o bool: a true or false (boolean) value 650 o time: a timestamp, expressed in terms of UTC. The precision of 651 the timestamp is taken to be unambiguous based on its 652 representation. 654 o address: an identifier of a network-level entity, including an 655 address family. The address family is presumed to be implicit in 656 the format of the message, or explicitly stored. Addresses may 657 represent specific endpoints or entire networks. 659 o url: a uniform resource locator 661 o object: a structured object, serialized according to the 662 serialization rules of the underlying representation. 664 4.1.3. Augmented Registry Information 666 Additional keys beyond prim, desc, and name may appear in an mPlane 667 registry to augment information about each element. The following 668 additional registry keys have been found useful by some implementors 669 of the protocol: 671 o units: If applicable, string describing the units in which the 672 element is expressed; equal to the units part of a structured name 673 if present. 675 o ipfix-eid: The element ID of the equivalent IPFIX [RFC7011] 676 Information Element. 678 o ipfix-pen: The SMI Private Enterprise Number of the equivalent 679 IPFIX [RFC7011] Information Element, if any. 681 4.2. Message Types 683 Workflows in mPlane are built around the Capability - Specification - 684 Result cycle. Capabilities, Specifications, and Results are kinds of 685 statements: a Capability is a statement that a Component can perform 686 some action (generally a measurement); a Specification is a statement 687 that a Client would like a Component to perform the action advertised 688 in a Capability; and a Result is a statement that a Component 689 measured a given set of values at a given point in time according to 690 a Specification. 692 Other types of messages outside this nominal cycle are referred to as 693 notifications. Types of notifications include Withdrawals, 694 Interrupts, Receipts, Redemptions, and Exceptions. These notify 695 Clients or Components of conditions within the measurement 696 infrastructure itself, as opposed to directly containing information 697 about measurements or observations. 699 Messages may also be grouped together into a single envelope message. 700 Envelopes allow multiple messages to be represented within a single 701 message, for example multiple Results pertaining to the same Receipt; 702 and multiple Capabilities or Specifications to be transferred in a 703 single transaction in the underlying session protocol. 705 The following types of messages are supported by the mPlane protocol: 707 4.2.1. Capability and Withdrawal 709 A Capability is a statement of a Component's ability and willingness 710 to perform a specific operation, conveyed from a Component to a 711 Client. It does not represent a guarantee that the specific 712 operation can or will be performed at a specific point in time. 714 A withdrawal is a notification of a Component's inability or 715 unwillingness to perform a specific operation. It cancels a 716 previously advertised Capability. A withdrawal can also be sent in 717 reply to a Specification which attempts to invoke a Capability no 718 longer offered. 720 4.2.2. Specification and Interrupt 722 A Specification is a statement that a Component should perform a 723 specific operation, conveyed from a Client to a Component. It can be 724 conceptually viewed as a Capability whose parameters have been filled 725 in with values. 727 An interrupt is a notification that a Component should stop 728 performing a specific operation, conveyed from Client to Component. 729 It terminates a previously sent Specification. If the Specification 730 uses indirect export, the indirect export will simply stop running. 731 If the Specification has pending Results, those Results are returned 732 in response to the interrupt. 734 4.2.3. Result 736 A Result is a statement produced by a Component that a particular 737 measurement was taken and the given values were observed, or that a 738 particular operation or analysis was performed and a the given values 739 were produced. It can be conceptually viewed as a Specification 740 whose Result columns have been filled in with values. Note that, in 741 keeping with the stateless nature of the mPlane protocol, a Result 742 contains the full set of parameters from which it was derived. 744 Note that not every Specification will lead to a Result being 745 returned; for example, in case of indirect export, only a receipt 746 which can be used for future interruption will be returned, as the 747 results will be conveyed to a third Component using an external 748 protocol. 750 4.2.4. Receipt and Redemption 752 A receipt is returned instead of a Result by a Component in response 753 to a Specification which either: 755 o will never return results, as it initiated an indirect export, or 757 o will not return results immediately, as the operation producing 758 the results will have a long run time. 760 Receipts have the same content Specification they are returned for. 761 A Component may optionally add a token section, which can be used in 762 future redemptions or interruptions by the Client. The content of 763 the token is an opaque string generated by the Component. 765 A redemption is sent from a Client to a Component for a previously 766 received receipt to attempt to retrieve delayed results. It may 767 contain only the token section, the token and temporal scope, or all 768 sections of the received receipt. 770 When the temporal scope of a redemption for a running measurement is 771 different than the temporal scope of the original Specification, it 772 is treated by the Component as a partial redemption: all rows 773 resulting from the measurement within the specified temporal scope 774 are returned as a Result. Otherwise, a Component responds with a 775 Result only when the measurement is complete; otherwise, another 776 receipt is returned. 778 Note that redemptions are optional: when a Component has a Result 779 available for a Client after some period of time, it may send it 780 immediately, without waiting for a redemption to retrieve it. 782 4.2.5. Exception 784 An exception is sent from a Client to a Component or from a Component 785 to a Client to signal an exceptional condition within the 786 infrastructure itself. They are not meant to signal exceptional 787 conditions within a measurement performed by a Component; see 788 Section 6.3 for more. An exception contains only two sections: an 789 optional token referring back to the message to which the exception 790 is related (if any), and a message section containing free-form, 791 preferably human readable information about the exception. 793 4.2.6. Envelope 795 An envelope is used to contain other messages. Message containment 796 is necessary in contexts in which multiple mPlane messages must be 797 grouped into a single transaction in the underlying session protocol. 798 It is legal to group any kind of message, and to mix messages of 799 different types, in an envelope. However, in the current revision of 800 the protocol, envelopes are primarily intended to be used for three 801 distinct purposes: 803 o To group multiple Capabilities together within a single message 804 (e.g., all the Capabilities a given Component has). 806 o To return multiple Results for a single receipt or Specification. 808 o To group multiple Specifications into a single message. 810 4.3. Message Sections 812 Each message is made up of sections, as described in the subsection 813 below. The following table shows the presence of each of these 814 sections in each of the message types supported by mPlane: "req" 815 means the section is required, "opt" means it is optional, and "tok" 816 means it may be replaced by reference via a token when available 817 (i.e., in withdrawals and redemptions); see the subsection on each 818 message section for details. 820 +----------------+---------+-------+--------+---------+----------+ 821 | Section | Cap. | Spec. | Result | Receipt | Envelope | 822 +----------------+---------+-------+--------+---------+----------+ 823 | Verb | req | req | req. | req. | | 824 | | | | | | | 825 | Content Type | | | | | req | 826 | | | | | | | 827 | "version" | req | req | req | req | req | 828 | | | | | | | 829 | "registry" | req | req | req | opt | | 830 | | | | | | | 831 | "label" | opt | opt | opt | opt | opt | 832 | | | | | | | 833 | "when" | req | req | req | req | | 834 | | | | | | | 835 | "parameters" | req/tok | req | req | opt/tok | | 836 | | | | | | | 837 | "metadata" | opt/tok | opt | opt | opt/tok | | 838 | | | | | | | 839 | "results" | req/tok | req | req | opt/tok | | 840 | | | | | | | 841 | "resultvalues" | | | req | | | 842 | | | | | | | 843 | "export" | opt | opt | opt | opt | | 844 | | | | | | | 845 | "link" | opt | opt | | | | 846 | | | | | | | 847 | "token" | opt | opt | opt | opt | opt | 848 | | | | | | | 849 | "contents" | | | | | req | 850 +----------------+---------+-------+--------+---------+----------+ 852 Table 1: Message Sections for Each Message Type 854 Withdrawals take the same sections as Capabilities; and redemptions 855 and interrupts take the same sections as receipts. Exceptions are 856 not shown in this table. 858 4.3.1. Message Type and Verb 860 The verb is the action to be performed by the Component. The 861 following verbs are supported by the base mPlane protocol, but 862 arbitrary verbs may be specified by applications: 864 o "measure": Perform a measurement 866 o "query": Query a database about a past measurement 867 o "collect": Receive Results via indirect export 869 o "callback": Used for callback control in Component-initiated 870 workflows 872 In the JSON representation of mPlane messages, the verb is the value 873 of the key corresponding to the message's type, represented as a 874 lowercase string (e.g. "Capability", "Specification", "result" and 875 so on). 877 Roughly speaking, probes implement "measure" Capabilities, and 878 repositories implement "query" and "collect" Capabilities. Of 879 course, any single Component can implement Capabilities with any 880 number of different verbs. 882 Within the SDK, the primary difference between "measure" and "query" 883 is that the temporal scope of a "measure" Specification is taken to 884 refer to when the measurement should be scheduled, while the temporal 885 scope of a "query" Specification is taken to refer to the time window 886 (in the past) of a query. 888 Envelopes have no verb; instead, the value of the "envelope" key is 889 the kind of messages the envelope contains, or "message" if the 890 envelope contains a mixture of different unspecified kinds of 891 messages. 893 4.3.2. Version 895 The "version" section contains the version of the mPlane protocol to 896 which the message conforms, as an integer serially incremented with 897 each new protocol revision. This section is required in all 898 messages. This document describes version 2 of the protocol. 900 4.3.3. Registry 902 The "registry" section contains the URL identifying the element 903 registry used by this message, and from which the registry can be 904 retrieved. This section is required in all messages containing 905 element names (statements, and receipts/redemptions/interrupts not 906 using tokens for identification; see the "token" section). 908 4.3.4. Label 910 The "label" section of a statement contains a human-readable label 911 identifying it, intended solely for use when displaying information 912 about messages in user interfaces. Results, receipts, redemptions, 913 and interrupts inherit their label from the Specification from which 914 they follow; otherwise, Client and Component software can arbitrarily 915 assign labels . The use of labels is optional in all messages, but as 916 labels do greatly ease human-readability of arbitrary messages within 917 user interfaces, their use is recommended. 919 mPlane Clients and Components should never use the label as a unique 920 identifier for a message, or assume any semantic meaning in the label 921 - the test of message equality and relatedness is always based upon 922 the schema and values as in Section 4.4. 924 4.3.5. Temporal Scope (When) 926 The "when" section of a statement contains its temporal scope. 928 A temporal scope refers to when a measurement can be run (in a 929 Capability), when it should be run (in a Specification), or when it 930 was run (in a Result). Temporal scopes can be either absolute or 931 relative, and may have an optional period, referring to how often 932 single measurements should be taken. 934 The general form of a temporal scope (in BNF-like syntax) is as 935 follows: 937 when = | # A single point in time 938 | # A range in time 939 ' / ' # A range with a period 941 singleton = | # absolute singleton 942 'now' # relative singleton 944 range = ' ... ' | # absolute range 945 ' + ' | # relative range 946 'now' ' ... ' | # definite future 947 'now' ' + ' | # relative future 948 ' ... ' 'now' | # definite past 949 'past ... now' | # indefinite past 950 'now ... future' | # indefinite future 951 ' ... ' 'future' | # absolute indefinite future 952 'past ... future' | # forever 954 duration = [ 'd' ] # days 955 [ 'h' ] # hours 956 [ 'm' ] # minute 957 [ 's' ] # seconds 959 iso8601 = '-' '-' [' ' ':' ':' [ '.' ]] 961 All absolute times are always given in UTC and expressed in ISO8601 962 format with variable precision. 964 In Capabilities, if a period is given it represents the minimum 965 period supported by the measurement; this is done to allow rate 966 limiting. If no period is given, the measurement is not periodic. A 967 Capability with a period can only be fulfilled by a Specification 968 with period greater than or equal to the period in the Capability. 969 Conversely, a Capability without a period can only be fulfilled by a 970 Specification without a period. 972 Within a Result, only absolute ranges are allowed within the temporal 973 scope, and refers to the time range of the measurements contributing 974 to the Result. Note that the use of absolute times here implies that 975 the Components and Clients within a domain should have relatively 976 well-synchronized clocks, e.g., to be synchronized using the Network 977 Time Protocol [RFC5905] in order for Results to be temporally 978 meaningful. 980 So, for example, an absolute range in time might be expressed as: 982 "when: 2009-02-20 13:02:15 ... 2014-04-04 04:27:19" 984 A relative range covering three and a half days might be: 986 "when: 2009-04-04 04:00:00 + 3d12h" 988 In a Specification for running an immediate measurement for three 989 hours every seven and a half minutes: 991 "when: now + 3h / 7m30s" 993 In a Capability noting that a Repository can answer questions about 994 the past: 996 "when: past ... now". 998 In a Specification requesting that a measurement run from a specified 999 point in time until interrupted: 1001 "when: 2017-11-23 18:30:00 ... future" 1003 4.3.6. Parameters 1005 The "parameters" section of a message contains an ordered list of the 1006 parameters for a given measurement: values which must be provided by 1007 a Client to a Component in a Specification to convey the specifics of 1008 the measurement to perform. Each parameter in an mPlane message is a 1009 key-value pair, where the key is the name of an element from the 1010 element registry. In Specifications and Results, the value is the 1011 value of the parameter. In Capabilities, the value is a constraint 1012 on the possible values the Component will accept for the parameter in 1013 a subsequent Specification. 1015 Four kinds of constraints are currently supported for mPlane 1016 parameters: 1018 o No constraint: all values are allowed. This is signified by the 1019 special constraint string '"*"'. 1021 o Single value constraint: only a single value is allowed. This is 1022 intended for use for Capabilities which are conceivably 1023 configurable, but for which a given Component only supports a 1024 single value for a given parameter due to its own out-of-band 1025 configuration or the permissions of the Client for which the 1026 Capability is valid. For example, the source address of an active 1027 measurement of a single-homed probe might be given as 1028 '"source.ip4: 192.0.2.19"'. 1030 o Set constraint: multiple values are allowed, and are explicitly 1031 listed, separated by the '","' character. For example, a multi- 1032 homed probe allowing two potential source addresses on two 1033 different networks might be given as '"source.ip4: 192.0.2.19, 1034 192.0.3.21"'. 1036 o Range constraint: multiple values are allowed, between two ordered 1037 values, separated by the special string '"..."'. Range 1038 constraints are inclusive. A measurement allowing a restricted 1039 range of source ports might be expressed as '"source.port: 32768 1040 ... 65535"' 1042 o Prefix constraint: multiple values are allowed within a single 1043 network, as specified by a network address and a prefix. A prefix 1044 constraint may be satisfied by any network of host address 1045 completely contained within the prefix. An example allowing 1046 probing of any host within a given /24 might be '"destination.ip4: 1047 192.0.2.0/24"'. 1049 Parameter and constraint values must be a representation of an 1050 instance of the primitive type of the associated element. 1052 4.3.7. Metadata 1054 The "metadata" section contains measurement metadata: key-value pairs 1055 associated with a Capability inherited by its Specification and 1056 Results. Metadata can also be thought of as immutable parameters. 1057 This is intended to represent information which can be used to make 1058 decisions at the Client as to the applicability of a given Capability 1059 (e.g. details of algorithms used or implementation-specific 1060 information) as well as to make adjustments at post-measurement 1061 analysis time when contained within Results. 1063 An example metadata element might be '"measurement.identifier: qof"', 1064 which identifies the underlying tool taking measurements, such that 1065 later analysis can correct for known peculiarities in the 1066 implementation of the tool. Another example might be 1067 '"location.longitude = 8.55272"', which while not particularly useful 1068 for analysis purposes, can be used to draw maps of measurements. 1070 4.3.8. Result Columns and Values 1072 Results are represented using two sections: "results" which identify 1073 the elements to be returned by the measurement, and "resultvalues" 1074 which contains the actual values. "results" appear in all statements, 1075 while "resultvalues" appear only in Result messages. 1077 The "results" section contains an ordered list of result columns for 1078 a given measurement: names of elements which will be returned by the 1079 measurement. The result columns are identified by the names of the 1080 elements from the element registry. 1082 The "resultvalues" section contains an ordered list of ordered lists 1083 (or, rather, a two dimensional array) of values of results for a 1084 given measurement, in row-major order. The columns in the result 1085 values appear in the same order as the columns in the "results" 1086 section. 1088 Values for each column must be a representation of an instance of the 1089 primitive type of the associated result column element. 1091 4.3.9. Export 1093 The "export" section contains a URL or partial URL for indirect 1094 export. Its meaning depends on the kind and verb of the message: 1096 o For Capabilities with the "collect" verb, the "export" section 1097 contains the URL of the collector which can accept indirect export 1098 for the schema defined by the "parameters" and "results" sections 1099 of the Capability, using the protocol identified by the URL's 1100 schema. 1102 o For Capabilities with any verb other than "collect", the "export" 1103 section contains either the URL of a collector to which the 1104 Component can indirectly export results, or a URL schema 1105 identifying a protocol over which the Component can export to 1106 arbitrary collectors. 1108 o For Specifications with any verb other than "collect", the 1109 "export" section contains the URL of a collector to which the 1110 Component should indirectly export results. A receipt will be 1111 returned for such Specifications. 1113 If a Component can indirectly export or indirectly collect using 1114 multiple protocols, each of those protocols must be identified by its 1115 own Capability; Capabilities with an "export" section can only be 1116 used by Specifications with a matching "export" section. 1118 4.3.10. Link 1120 The "link" section contains the URL to which messages in the next 1121 step in the workflow (i.e. a Specification for a Capability, a Result 1122 or receipt for a Specification) can be sent, providing indirection. 1123 The link URL must currently have the schema "wss", and refers to the 1124 URL to which to initiate a connection. 1126 If present in a Capability, the Client must send Specifications for 1127 the given Capability to the Component at the URL given in order to 1128 use the Capability, connecting to the URL if no connection is 1129 currently established. If present in a Specification, the Component 1130 must send Results for the given Specification back to the Client at 1131 the URL given, connecting to the URL if no connection is currently 1132 established. 1134 4.3.11. Token 1136 The "token" section contains an arbitrary string by which a message 1137 may be identified in subsequent communications in an abbreviated 1138 fashion. Unlike labels, tokens are not necessarily intended to be 1139 human-readable; instead, they provide a way to reduce redundancy on 1140 the wire by replacing the parameters, metadata, and results sections 1141 in messages within a workflow, at the expense of requiring more state 1142 at Clients and Components. Their use is optional. 1144 Tokens are scoped to the association between the Component and Client 1145 in which they are first created; i.e., at a Component, the token will 1146 be associated with the Client's identity, and vice-versa at a Client. 1147 Tokens should be created with sufficient entropy to avoid collision 1148 from independent processes at the same Client or token reuse in the 1149 case of Client or Component state loss at restart. 1151 If a Capability contains a token, it may be subsequently withdrawn by 1152 the same Component using a withdrawal containing the token instead of 1153 the parameters, metadata, and results sections. 1155 If a Specification contains a token, it may be answered by the 1156 Component with a receipt containing the token instead of the 1157 parameters, metadata, and results sections. A Specification 1158 containing a token may likewise be interrupted by the Client with an 1159 interrupt containing the token. A Component must not answer a 1160 Specification with a token with a receipt or Result containing a 1161 different token, but the token may be omitted in subsequent receipts 1162 and Results. 1164 If a receipt contains a token, it may be redeemed by the same Client 1165 using a redemption containing the token instead of the parameters, 1166 metadata, and results sections. 1168 4.3.12. Contents 1170 The "contents" section appears only in envelopes, and is an ordered 1171 list of messages. If the envelope's kind identifies a message kind, 1172 the contents may contain only messages of the specified kind, 1173 otherwise if the kind is "message", the contents may contain a mix of 1174 any kind of message. 1176 4.4. Message Uniqueness and Idempotence 1178 Messages in the mPlane protocol are intended to support state 1179 distribution: Capabilities, Specifications, and Results are meant to 1180 be complete declarations of the state of a given measurement. In 1181 order for this to hold, it must be possible for messages to be 1182 uniquely identifiable, such that duplicate messages can be 1183 recognized. With one important exception (i.e., Specifications with 1184 relative temporal scopes), messages are idempotent: the receipt of a 1185 duplicate message at a Client or Component is a null operation. 1187 4.4.1. Message Schema 1189 The combination of elements in the "parameters" and "results" 1190 sections, together with the registry from which these elements are 1191 drawn, is referred to as a message's schema. The schema of a 1192 measurement can be loosely thought of as the definition of the table, 1193 rows of which the message represents. 1195 The schema contributes not only to the identity of a message, but 1196 also to the semantic interpretation of the parameter and result 1197 values. The meanings of element values in mPlane are dependent on 1198 the other elements present in the message; in other words, the key to 1199 interpreting an mPlane message is that the unit of semantic identity 1200 is a message. For example, the element '"destination.ip4"' as a 1201 parameter means "the target of a given active measurement" when 1202 together with elements describing an active metric (e.g. 1204 '"delay.twoway.icmp.us"'), but "the destination of the packets in a 1205 flow" when together with other elements in result columns describing 1206 a passively-observed flow. 1208 The interpretation of the semantics of an entire message is 1209 application-specific. The protocol does not forbid the transmission 1210 of messages representing semantically meaningless or ambiguous 1211 schemas. 1213 4.4.2. Message Identity 1215 A message's identity is composed of its schema, together with its 1216 temporal scope, metadata, parameter values, and indirect export 1217 properties. Concretely, the full content of the "registry", "when", 1218 "parameters", "metadata", "results", and "export" sections taken 1219 together comprise the message's identity. 1221 One convenience feature complicates this somewhat: when the temporal 1222 scope is not absolute, multiple Specifications may have the same 1223 literal temporal scope but refer to different measurements. In this 1224 case, the current time at the Client or Component when a message is 1225 invoked must be taken as part of the message's identity as well. 1226 Implementations may use hashes over the values of the message's 1227 identity sections to uniquely identify messages; e.g. to generate 1228 message tokens. 1230 4.5. Designing Measurement and Repository Schemas 1232 As noted, the key to integrating a measurement tool into an mPlane 1233 infrastructure is properly defining the schemas for the measurements 1234 and queries it performs, then defining those schemas in terms of 1235 mPlane Capabilities. Specifications and Results follow naturally 1236 from Capabilities, and the mPlane SDK allows Python methods to be 1237 bound to Capabilities in order to execute them. A schema should be 1238 defined such that the set of parameters, the set of result columns, 1239 and the verb together naturally and uniquely define the measurement 1240 or the query being performed. For simple metrics, this is achieved 1241 by encoding the entire meaning of the metric in its name. For 1242 example, "delay.twoway.icmp.us" as a result column together with 1243 "source.ip4" and "destination.ip4" as parameters uniquely defines a 1244 single ping measurement, measured via ICMP, expressed in 1245 microseconds. 1247 Aggregate measurements are defined by returning metrics with 1248 aggregations: "delay.twoway.icmp.min.us", "delay.twoway.icmp.max.us", 1249 "delay.twoway.icmp.mean.us", and "delay.twoway.icmp.count.us" as 1250 result columns represent aggregate ping measurements with multiple 1251 samples. 1253 Note that mPlane Results may contain multiple rows. In this case, 1254 the parameter values in the Result, taken from the Specification, 1255 apply to all rows. In this case, the rows are generally 1256 differentiated by the values in one or more result columns; for 1257 example, the "time" element can be used to represent time series, or 1258 the "hops.ip" different elements along a path between source and 1259 destination, as in a traceroute measurement. 1261 For measurements taken instantaneously, the verb "measure" should be 1262 used; for direct queries from repositories, the verb "query" should 1263 be used. Other actions that cannot be differentiated by schema alone 1264 should be differentiated by a custom verb. 1266 When integrating a repository into an mPlane infrastructure, only a 1267 subset of the queries the repository can perform will generally be 1268 exposed via the mPlane interface. Consider a generic repository 1269 which provides an SQL interface for querying data; wrapping the 1270 entire set of possible queries in specific Capabilities would be 1271 impossible, while providing direct access to the underlying SQL (for 1272 instance, by creating a custom registry with a "query.sql" string 1273 element to be used as a parameter) would make it impossible to 1274 differentiate Capabilities by schema (thereby making the 1275 interoperability benefits of mPlane integration pointless). Instead, 1276 specific queries to be used by Clients in concert with Capabilities 1277 provided by other Components are each wrapped within a separate 1278 Capability, analogous to stored procedure programming in many 1279 database engines. Of course, Clients which do speak the precise 1280 dialect of SQL necessary can integrate directly with the repository 1281 separate from the Capabilities provided over mPlane. 1283 5. Representations and Session Protocols 1285 The mPlane protocol is built atop an abstract data model in order to 1286 support multiple representations and session protocols. The 1287 canonical representation supported by the present SDK involves JSON 1288 [RFC7159] objects transported via Websockets [RFC6455] over TLS 1289 [RFC5246] (known by the "wss" URL schema). 1291 5.1. JSON representation 1293 In the JSON representation, an mPlane message is a JSON object, 1294 mapping sections by name to their contents. The name of the message 1295 type is a special section key, which maps to the message's verb, or 1296 to the message's content type in the case of an envelope. 1298 Each section name key in the object has a value represented in JSON 1299 as follows: 1301 o "version" : an integer identifying the mPlane protocol version 1302 used by the message. 1304 o "registry" : a URL identifying the registry from which element 1305 names are taken. 1307 o "label" : an arbitrary string. 1309 o "when" : a string containing a temporal scope, as described in 1310 Section 4.3.5. 1312 o "parameters" : a JSON object mapping (non-qualified) element 1313 names, either to constraints or to parameter values, as 1314 appropriate, and as described in Section 4.3.6. 1316 o "metadata" : a JSON object mapping (non-qualified) element names 1317 to metadata values. 1319 o "results" : an array of element names. 1321 o "resultvalues" : an array of arrays of element values in row major 1322 order, where each row array contains values in the same order as 1323 the element names in the "results" section. 1325 o "export" : a URL for indirect export. 1327 o "link" : a URL for message indirection. 1329 o "token" : an arbitrary string. 1331 o "contents" : an array of objects containing messages. 1333 5.1.1. Textual representations of element values 1335 Each primitive type is represented as a value in JSON as follows, 1336 following the Textual Representation of IPFIX Abstract Data Types 1337 defined in [RFC7373]. 1339 Natural and real values are represented in JSON using native JSON 1340 representation for numbers. 1342 Booleans are represented by the reserved words "true" and "false". 1344 Strings and URLs are represented as JSON strings, subject to JSON 1345 escaping rules. 1347 Addresses are represented as dotted quads for IPv4 addresses as they 1348 would be in URLs, and canonical IPv6 textual addresses as in section 1349 2.2 of [RFC4291] as updated by section 4 of [RFC5952]. When 1350 representing networks, addresses may be suffixed as in CIDR notation, 1351 with a '"/"' character followed by the mask length in bits n, 1352 provided that the least significant 32 - n or 128 - n bits of the 1353 address are zero, for IPv4 and IPv6 respectively. 1355 Timestamps are represented in [RFC3339] and ISO 8601, with two 1356 important differences. First, all mPlane timestamps are are 1357 expressed in terms of UTC, so time zone offsets are neither required 1358 nor supported, and are always taken to be 0. Second, fractional 1359 seconds are represented with a variable number of digits after an 1360 optional decimal point after the fraction. 1362 Objects are represented as JSON objects. 1364 5.1.2. Example mPlane Capabilities and Specifications in JSON 1366 To illustrate how mPlane messages are encoded, we consider first two 1367 Capabilities for a very simple application - ping - as mPlane JSON 1368 Capabilities. The following Capability states that the Component can 1369 measure ICMP two-way delay from 192.0.2.19 to anywhere on the IPv4 1370 Internet, with a minimum delay between individual pings of 1 second, 1371 returning aggregate statistics: 1373 { 1374 "capability": "measure", 1375 "version": 0, 1376 "registry": "https://example.com/mplane/registry/core", 1377 "label": "ping-aggregate", 1378 "when": "now ... future / 1s", 1379 "parameters": {"source.ip4": "192.0.2.19", 1380 "destination.ip4": "*"}, 1381 "results": ["delay.twoway.icmp.us.min", 1382 "delay.twoway.icmp.us.mean", 1383 "delay.twoway.icmp.us.50pct", 1384 "delay.twoway.icmp.us.max", 1385 "delay.twoway.icmp.count"] 1386 } 1388 In contrast, the following Capability would return timestamped 1389 singleton delay measurements given the same parameters: 1391 { 1392 "capability": "measure", 1393 "version": 0, 1394 "registry": "https://example.com/mplane/registry/core", 1395 "label": "ping-singletons", 1396 "when": "now ... future / 1s", 1397 "parameters": {"source.ip4": "192.0.2.19", 1398 "destination.ip4": "*"}, 1399 "results": ["time", 1400 "delay.twoway.icmp.us"] 1401 } 1403 A Specification is merely a Capability with filled-in parameters, 1404 e.g.: 1406 { 1407 "specification": "measure", 1408 "version": 0, 1409 "registry": "https://example.com/mplane/registry/core", 1410 "label": "ping-aggregate-three-thirtythree", 1411 "token": "0f31c9033f8fce0c9be41d4942c276e4", 1412 "when": "now + 30s / 1s", 1413 "parameters": {"source.ip4": "192.0.2.19", 1414 "destination.ip4": "192.0.3.33"}, 1415 "results": ["delay.twoway.icmp.us.min", 1416 "delay.twoway.icmp.us.mean", 1417 "delay.twoway.icmp.us.50pct", 1418 "delay.twoway.icmp.us.max", 1419 "delay.twoway.icmp.count"] 1420 } 1422 Results are merely Specifications with result values filled in and an 1423 absolute temporal scope: 1425 { 1426 "result": "measure", 1427 "version": 0, 1428 "registry": "https://example.com/mplane/registry/core", 1429 "label": "ping-aggregate-three-thirtythree", 1430 "token": "0f31c9033f8fce0c9be41d4942c276e4", 1431 "when": 2014-08-25 14:51:02.623 ... 2014-08-25 14:51:32.701 / 1s", 1432 "parameters": {"source.ip4": "192.0.2.19", 1433 "destination.ip4": "192.0.3.33"}, 1434 "results": ["delay.twoway.icmp.us.min", 1435 "delay.twoway.icmp.us.mean", 1436 "delay.twoway.icmp.us.50pct", 1437 "delay.twoway.icmp.us.max", 1438 "delay.twoway.icmp.count"], 1439 "resultvalues": [ [ 23901, 1440 29833, 1441 27619, 1442 66002, 1443 30] ] 1444 } 1446 More complex measurements can be modeled by mapping them back to 1447 tables with multiple rows. For example, a traceroute Capability 1448 would be defined as follows: 1450 { 1451 "capability": "measure", 1452 "version": 0, 1453 "registry": "https://example.com/mplane/registry/core", 1454 "label": "traceroute", 1455 "when": "now ... future / 1s", 1456 "parameters": {"source.ip4": "192.0.2.19", 1457 "destination.ip4": "*", 1458 "hops.ip.max": "0..32"}, 1459 "results": ["time", 1460 "intermediate.ip4", 1461 "hops.ip", 1462 "delay.twoway.icmp.us"] 1463 } 1465 with a corresponding Specification: 1467 { 1468 "specification": "measure", 1469 "version": 0, 1470 "registry": "https://example.com/mplane/registry/core", 1471 "label": "traceroute-three-thirtythree", 1472 "token": "2f4123588b276470b3641297ae85376a", 1473 "when": "now", 1474 "parameters": {"source.ip4": "192.0.2.19", 1475 "destination.ip4": "192.0.3.33", 1476 "hops.ip.max": 32}, 1477 "results": ["time", 1478 "intermediate.ip4", 1479 "hops.ip", 1480 "delay.twoway.icmp.us"] 1481 } 1483 and an example result: 1485 { 1486 "result": "measure", 1487 "version": 0, 1488 "registry": "https://example.com/mplane/registry/core", 1489 "label": "traceroute-three-thirtythree", 1490 "token": "2f4123588b276470b3641297ae85376a, 1491 "when": "2014-08-25 14:53:11.019 ... 2014-08-25 14:53:12.765", 1492 "parameters": {"source.ip4": "192.0.2.19", 1493 "destination.ip4": "192.0.3.33", 1494 "hops.ip.max": 32}, 1495 "results": ["time", 1496 "intermediate.ip4", 1497 "hops.ip", 1498 "delay.twoway.icmp.us"], 1499 "resultvalues": [ [ "2014-08-25 14:53:11.019", "192.0.2.1", 1500 1, 162 ], 1501 [ "2014-08-25 14:53:11.220", "217.147.223.101", 1502 2, 15074 ], 1503 [ "2014-08-25 14:53:11.570", "77.109.135.193", 1504 3, 30093 ], 1505 [ "2014-08-25 14:53:12.091", "77.109.135.34", 1506 4, 34979 ], 1507 [ "2014-08-25 14:53:12.310", "192.0.3.1", 1508 5, 36120 ], 1509 [ "2014-08-25 14:53:12.765", "192.0.3.33", 1510 6, 36202 ] 1511 ] 1513 } 1514 Indirect export to a repository with subsequent query requires three 1515 Capabilities: one in which the repository advertises its ability to 1516 accept data over a given external protocol, one in which the probe 1517 advertises its ability to export data of the same type using that 1518 protocol, and one in which the repository advertises its ability to 1519 answer queries about the stored data. Returning to the aggregate 1520 ping measurement, first let's consider a repository which can accept 1521 these measurements via direct POST of mPlane Result messages: 1523 { 1524 "capability": "collect", 1525 "version": 0, 1526 "registry": "https://example.com/mplane/registry/core", 1527 "label": "ping-aggregate-collect", 1528 "when": "past ... future", 1529 "export": "wss://repository.example.com:4343/", 1530 "parameters": {"source.ip4": "*", 1531 "destination.ip4": "*"}, 1532 "results": ["delay.twoway.icmp.us.min", 1533 "delay.twoway.icmp.us.mean", 1534 "delay.twoway.icmp.us.50pct", 1535 "delay.twoway.icmp.us.max", 1536 "delay.twoway.icmp.count"] 1537 } 1539 This Capability states that the repository at 1540 "wss://repository.example.com:4343/" will accept mPlane Result 1541 messages matching the specified schema, without any limitations on 1542 time. Note that this schema matches that of the export Capability 1543 provided by the probe: 1545 { 1546 "capability": "measure", 1547 "version": 0, 1548 "registry": "https://example.com/mplane/registry/core", 1549 "label": "ping-aggregate-export", 1550 "when": "now ... future / 1s", 1551 "export": "wss", 1552 "parameters": {"source.ip4": "192.0.2.19", 1553 "destination.ip4": "*"}, 1554 "results": ["delay.twoway.icmp.us.min", 1555 "delay.twoway.icmp.us.mean", 1556 "delay.twoway.icmp.us.50pct", 1557 "delay.twoway.icmp.us.max", 1558 "delay.twoway.icmp.count"] 1559 } 1560 which differs only from the previous probe Capability in that it 1561 states that Results can be exported via the "wss" protocol. 1562 Subsequent queries can be sent to the repository in response to the 1563 query Capability: 1565 { 1566 "capability": "query", 1567 "version": 0, 1568 "registry": "https://example.com/mplane/registry/core", 1569 "label": "ping-aggregate-query", 1570 "when": "past ... future", 1571 "link": "wss://repo.example.com:4343/", 1572 "parameters": {"source.ip4": "*", 1573 "destination.ip4": "*"}, 1574 "results": ["delay.twoway.icmp.us.min", 1575 "delay.twoway.icmp.us.mean", 1576 "delay.twoway.icmp.us.50pct", 1577 "delay.twoway.icmp.us.max", 1578 "delay.twoway.icmp.count"] 1579 } 1581 The examples in this section use the following registry: 1583 { "registry-format": "mplane-0", 1584 "registry-uri", "https://example.com/mplane/registry/core", 1585 "registry-revision": 0, 1586 "includes": [], 1587 "elements": [ 1588 { "name": "time", 1589 "prim": "time", 1590 "desc": "Time at which a single observation was taken" 1591 }, 1592 { "name": "source.ip4", 1593 "prim": "address", 1594 "desc": "Source (or probe) IPv4 address" 1595 }, 1596 { "name": "destination.ip4", 1597 "prim": "address", 1598 "desc": "Destination (or target) IPv4 address" 1599 }, 1600 { "name": "intermediate.ip4", 1601 "prim": "address", 1602 "desc": "IPv4 address of intermediate node on a path" 1603 }, 1604 { "name": "hops.ip", 1605 "prim": "natural", 1606 "desc": "IP-layer hops to identified node" 1607 }, 1608 { "name": "hops.ip.max", 1609 "prim": "natural", 1610 "desc": "Maximum number of IP-layer hops to measure" 1611 }, 1612 { "name": "delay.twoway.icmp.us", 1613 "prim": "natural", 1614 "desc": "Singleton two-way delay as measured via ICMP Echo" 1615 }, 1616 { "name": "delay.twoway.icmp.us.min", 1617 "prim": "natural", 1618 "desc": "Minimum two-way delay as measured via ICMP Echo" 1619 }, 1620 { "name": "delay.twoway.icmp.us.50pct", 1621 "prim": "natural", 1622 "desc": "Median two-way delay as measured via ICMP Echo" 1623 }, 1624 { "name": "delay.twoway.icmp.us.mean", 1625 "prim": "natural", 1626 "desc": "Mean two-way delay as measured via ICMP Echo" 1627 }, 1628 { "name": "delay.twoway.icmp.us.max", 1629 "prim": "natural", 1630 "desc": "Maximum two-way delay as measured via ICMP Echo" 1631 }, 1632 { "name": "delay.twoway.icmp.us.count", 1633 "prim": "natural", 1634 "desc": "Count of two-way delay samples ... " 1635 }, 1636 ] 1637 } 1639 5.2. mPlane over WebSockets over TLS 1641 The default session protocol for mPlane is WebSockets [RFC6455]. 1642 Once a WebSockets handshake between Client and Component is complete, 1643 messages are simply exchanged as outlined in Section 4.2 as JSON 1644 objects in WebSockets text frames over the channel. 1646 When WebSockets is used as a session protocol for mPlane, it MUST be 1647 used over TLS for mPlane message exchanges. Both TLS Clients and 1648 servers MUST present certificates for TLS mutual authentication. 1649 mPlane Components MUST use the certificate presented by the mPlane 1650 Client to determine the Client's identity, and therefore the 1651 Capabilities which it is authorized to invoke. mPlane Clients MUST 1652 use the certificate presented by the mPlane Component to authenticate 1653 the Results received. mPlane Clients and Components MUST NOT use 1654 network-layer address or name (e.g. derived from DNS PTR queries) 1655 information to identify peers. 1657 mPlane Components may either act as WebSockets servers, for Client- 1658 initiated connection establishment, or as WebSockets Clients, for 1659 Component-initiated connection establishment. In either case, it is 1660 the responsibility of the connection initiator to re-establish 1661 connection in case it is lost. In this case, the entity acting as 1662 WebSockets server SHOULD maintain a queue of pending mPlane messages 1663 to identified peers to be sent on reconnection. 1665 5.2.1. mPlane PKI for WebSockets 1667 The Clients and Components within an mPlane domain generally share a 1668 single certificate issuer, specific to a single mPlane domain. 1669 Issuing a certificate to a Client or Component then grants it 1670 membership within the domain. Any Client or Component within the 1671 domain can then communicate with Components and Clients within that 1672 domain. In a domain containing one or more supervisors, all Clients 1673 and Components within the domain can connect to a supervisor. This 1674 deployment pattern can be used to scale mPlane domains to large 1675 numbers of Clients and Components without needing to specifically 1676 configure each Client and Component identity at the supervisor. 1678 In the case of interdomain federation, where supervisors connect to 1679 each other, each supervisor will have its own issuer. In this case, 1680 each supervisor must be configured to trust each remote domain's 1681 issuer, but only to identify that domain's supervisor. This 1682 compartmentalization is necessary to keep one domain from authorizing 1683 Clients within another domain. 1685 5.2.2. Capability Advertisement for WebSockets 1687 When a connection is first established between a Client and a 1688 Component, regardless of whether the Client or the Component 1689 initiates the connection, the Component sends an envelope containing 1690 all the Capabilities it wishes to advertise to the Client, based on 1691 the Client's identity. 1693 5.2.3. mPlane Link and Export URLs for WebSockets 1695 Components acting as WebSockets servers (for Client-initiated 1696 connection establishment) are identified in the Link sections of 1697 Capabilities and receipts by URLs with the "wss:" schema. Similarly, 1698 Clients acting as WebSockets servers (for Component-initated 1699 connection establishment) are identified in the Link sections of 1700 Specifications by URLs with the "wss:" schema. 1702 When the "wss:" schema appears in the export section of the 1703 Capability, this represents the Component's willingness to establish 1704 a WebSockets connection over which mPlane Result messages will be 1705 pushed. A "wss:" schema URL in a Specification export section, 1706 similarly, directs the Component to the WebSockets server to push 1707 Results to. 1709 Path information in WebSockets URLs is presently unused by the mPlane 1710 protocol, but path information MUST be conserved. mPlane Clients and 1711 Components acting as WebSockets servers can use path information as 1712 they see fit, for example to separate Client and Component workflows 1713 on the same server (as on a supervisor), to run mPlane and other 1714 protocols over WebSockets on the same server, and/or to pass 1715 cryptographic tokens for additional context separation or 1716 authorization purposes. Future versions of the mPlane protocol may 1717 use path information in WebSockets URLs, but this path information 1718 will be relative to this conserved "base" URL, as opposed to relative 1719 to the root. 1721 6. Deployment Considerations 1723 This section outlines considerations for building larger-scale 1724 infrastructures from the building blocks defined in this document. 1726 6.1. Supervisors and Federation 1728 For simple infrastructures, a set of Components may be controlled 1729 directly by a Client. However, in more complex infrastructures 1730 providing support for multiple Clients, a supervisor can mediate 1731 between Clients and Components. This supervisor is responsible for 1732 collecting Capabilities from a set of Components, and providing 1733 Capabilities based on these to its Clients. From the point of view 1734 of the mPlane protocol, a supervisor is merely a combined Component 1735 and Client. The logic binding Client and Component interfaces within 1736 the supervisor is application-specific, as it involves the following 1737 operations according to the semantics of each application: 1739 o translating lower-level Capabilities from subordinate Components 1740 into higher-level (composed) Capabilities, according to the 1741 application's semantics 1743 o translating higher-level Specifications from subordinate 1744 Components into lower-level (decomposed) Specifications 1746 o relaying or aggregating Results from subordinate Components to 1747 supervisor Clients 1749 This arrangement is shown in Figure 3. 1751 ________________ 1752 | | 1753 | Client | 1754 | | 1755 ---------------- 1756 ^ n| | 1757 Capability | | | Specification 1758 | |1 v 1759 ________________ 1760 .-| Component |-. 1761 | ---------------- | 1762 | supervisor | 1763 | ________________ | 1764 \_| Client |_/ 1765 ---------------- 1766 ^ 1| | 1767 Capability | | | Specification 1768 | |m v 1769 ________________ 1770 | | 1771 | Component | 1772 | | 1773 ---------------- 1775 Figure 3: Simple mPlane architecture with a supervisor 1777 The set of Components which respond to Specifications from a single 1778 supervisor is referred to as an mPlane domain. Domain membership is 1779 also determined by the issuer of the certificates identifying the 1780 Clients, Components, and supervisor. Within a given domain, each 1781 Client and Component connects to only one supervisor. Underlying 1782 measurement Components and Clients may indeed participate in multiple 1783 domains, but these are separate entities from the point of view of 1784 the architecture. Interdomain measurement is supported by federation 1785 among supervisors: a local supervisor delegates measurements in a 1786 remote domain to that domain's supervisor. 1788 In addition to Capability composition and Specification 1789 decomposition, supervisors are responsible for Client and Component 1790 registration and authentication, as well as access control based on 1791 identity information provided by the session protocol (WebSockets) in 1792 the general case. 1794 The general responsibilities of a supervisor are elaborated in the 1795 subsections below: 1797 6.1.1. Component Registration 1799 In order to be able to use Components to perform measurements, the 1800 supervisor must register the Components associated with it. For 1801 Client-initiated workflows - large repositories and the address of 1802 the Components is often a configuration parameter of the supervisor. 1803 Capabilities describing the available measurements and queries at 1804 large-scale Components can even be part of the supervisor's 1805 externally managed static configuration, or can be dynamically 1806 retrieved and updated from the Components or from a Capability 1807 discovery server. 1809 For Component-initiated workflows, Components connect to the 1810 supervisor and send Capabilities and withdrawals, which requires the 1811 supervisor to maintain a set of Capabilities associated with a set of 1812 Components currently part of the mPlane infrastructure it supervises. 1814 6.1.2. Client Authentication 1816 For many Components - probes and simple repositories - very simple 1817 authentication often suffices, such that any Client with a 1818 certificate with an issuer recognized as valid is acceptable, and all 1819 Capabilities are available to. Larger repositories often need finer 1820 grained control, mapping specific peer certificates to identities 1821 internal to the repository's access control system (e.g. database 1822 users). 1824 In an mPlane infrastructure, it is therefore the supervisor's 1825 responsibility to map Client identities to the set of Capabilities 1826 each Client is authorized to access. This mapping is part of the 1827 supervisor's configuration. 1829 6.1.3. Capability Composition and Specification Decomposition 1831 The most dominant responsibility of the supervisor is composing 1832 Capabilities from its subordinate Components into aggregate 1833 Capabilities, and decomposing Specifications from Clients to more- 1834 specific Specifications to pass to each Component. This operation is 1835 always application-specific, as the semantics of the composition and 1836 decomposition operations depend on the Capabilities available from 1837 the Components, the granularity of the Capabilities to be provided to 1838 the Clients. 1840 6.2. Indirect Export 1842 Many common measurement infrastructures involve a large number of 1843 probes exporting large volumes of data to a (much) smaller number of 1844 repositories, where data is reduced and analyzed. Since (1) the 1845 mPlane protocol is not particularly well-suited to the bulk transfer 1846 of data and (2) fidelity is better ensured when minimizing 1847 translations between representations, the channel between the probes 1848 and the repositories is in this case external to mPlane. This 1849 indirect export channel runs either a standard export protocol such 1850 as IPFIX, or a proprietary protocol unique to the probe/repository 1851 pair. It coordinates an exporter which will produce and export data 1852 with a collector which will receive it. All that is necessary is 1853 that (1) the Client, exporter, and collector agree on a schema to 1854 define the data to be transferred and (2) the exporter and collector 1855 share a common protocol for export. 1857 Here, we consider a Client speaking to an exporter and a collector. 1858 The Client first receives an export Capability from the exporter 1859 (with verb "measure" and with a protocol identified in the "export" 1860 section) and a collection Capability from the collector (with the 1861 verb "collect" and with a URL in the "export" section describing 1862 where the exporter should export), either via a Client-initiated 1863 workflow or a Capability discovery server. The Client then sends a 1864 Specification to the exporter, which matches the schema and parameter 1865 constraints of both the export and collection Capabilities, with the 1866 collector's URL in the "export" section. 1868 The exporter initiates export to the collector using the specified 1869 protocol, and replies with a receipt that can be used to interrupt 1870 the export, should it have an indefinite temporal scope. In the 1871 meantime, it sends data matching the Capability's schema directly to 1872 the collector. 1874 This data, or data derived from the analysis thereof, can then be 1875 subsequently retrieved by a Client using a Client-initiated workflow 1876 to the collector. 1878 6.3. Error Handling in mPlane Workflows 1880 Any Component may signal an error to its Client or supervisor at any 1881 time by sending an exception message. While the taxonomy of error 1882 messages is at this time left up to each individual Component, given 1883 the weakly imperative nature of the mPlane protocol, exceptions 1884 should be used sparingly, and only to notify Components and Clients 1885 of errors with the mPlane infrastructure itself. 1887 It is generally presumed that diagnostic information about errors 1888 which may require external human intervention to correct will be 1889 logged at each Component; the mPlane exception facility is not 1890 intended as a replacement for logging facilities (such as syslog). 1892 Specifically, Components using Component-initiated connection 1893 establishment should not use the exception mechanism for common error 1894 conditions (e.g., device losing connectivity for small network-edge 1895 probes) - Specifications sent to such Components are expected to be 1896 best-effort. Exceptions should also not be returned for 1897 Specifications which would normally not be delayed but are due to 1898 high load - receipts should be used in this case, instead. Likewise, 1899 Specifications which cannot be fulfilled because they request the use 1900 of Capabilities that were once available but are no longer should be 1901 answered with withdrawals. 1903 Exceptions should always be sent in reply to messages sent to 1904 Components or Clients which cannot be handled due to a syntactic or 1905 semantic error in the message itself. 1907 7. Security Considerations 1909 The mPlane protocol allows the control of network measurement 1910 devices. The protocol itself uses WebSockets using TLS as a session 1911 layer. TLS mutual authentication must be used for the exchange of 1912 mPlane messages, as access control decisions about which Clients and 1913 Components are trusted for which Capabilities take identity 1914 information from the certificates TLS Clients and servers use to 1915 identify themselves. Current operational best security practices for 1916 the deployment of TLS-secured protocols must be followed for the 1917 deployment of mPlane. 1919 Indirect export, as a design feature, presents a potential for 1920 information leakage, as indirectly exported data is necessarily 1921 related to measurement data and control transported with the mPlane 1922 protocol. Though out of scope for this document, indirect export 1923 protocols used within an mPlane domain must be secured at least as 1924 well as the mPlane protocol itself. 1926 8. IANA Considerations 1928 This document has no actions for IANA. Future versions of this 1929 document, should it become a standards-track Specification, may 1930 specify the initial contents of a core mPlane registry to be managed 1931 by IANA. 1933 9. Contributors 1935 This document is based on Deliverable 1.4, the architecture and 1936 protocol Specification document produced by the mPlane project [D14], 1937 which is the work of the mPlane consortium, specifically Brian 1938 Trammell and Mirja Kuehlewind (the editors of this document), as well 1939 as Marco Mellia, Alessandro Finamore, Stefano Pentassuglia, Gianni De 1940 Rosa, Fabrizio Invernizzi, Marco Milanesio, Dario Rossi, Saverio 1941 Niccolini, Ilias Leontiadis, Tivadar Szemethy, Balas Szabo, Rolf 1942 Winter, Michael Faath, Benoit Donnet, and Dimitri Papadimitriou. 1944 10. Acknowledgments 1946 Thanks to Lingli Deng and Robert Kisteleki for feedback leading to 1947 the improvement of this document and the protocol. 1949 This work is supported by the European Commission under grant 1950 agreement FP7-318627 mPlane and H2020-688421 MAMI, and by the Swiss 1951 State Secretariat for Education, Research, and Innovation under 1952 contract no. 15.0268. This support does not imply endorsement of the 1953 contents of this document. 1955 11. Informative References 1957 [RFC3205] Moore, K., "On the use of HTTP as a Substrate", BCP 56, 1958 RFC 3205, DOI 10.17487/RFC3205, February 2002, 1959 . 1961 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 1962 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 1963 . 1965 [RFC4291] Hinden, R. and S. Deering, "IP Version 6 Addressing 1966 Architecture", RFC 4291, DOI 10.17487/RFC4291, February 1967 2006, . 1969 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1970 (TLS) Protocol Version 1.2", RFC 5246, 1971 DOI 10.17487/RFC5246, August 2008, 1972 . 1974 [RFC5905] Mills, D., Martin, J., Ed., Burbank, J., and W. Kasch, 1975 "Network Time Protocol Version 4: Protocol and Algorithms 1976 Specification", RFC 5905, DOI 10.17487/RFC5905, June 2010, 1977 . 1979 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 1980 Address Text Representation", RFC 5952, 1981 DOI 10.17487/RFC5952, August 2010, 1982 . 1984 [RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol", 1985 RFC 6455, DOI 10.17487/RFC6455, December 2011, 1986 . 1988 [RFC7011] Claise, B., Ed., Trammell, B., Ed., and P. Aitken, 1989 "Specification of the IP Flow Information Export (IPFIX) 1990 Protocol for the Exchange of Flow Information", STD 77, 1991 RFC 7011, DOI 10.17487/RFC7011, September 2013, 1992 . 1994 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1995 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 1996 2014, . 1998 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1999 Protocol (HTTP/1.1): Message Syntax and Routing", 2000 RFC 7230, DOI 10.17487/RFC7230, June 2014, 2001 . 2003 [RFC7373] Trammell, B., "Textual Representation of IP Flow 2004 Information Export (IPFIX) Abstract Data Types", RFC 7373, 2005 DOI 10.17487/RFC7373, September 2014, 2006 . 2008 [D14] Trammell, B., "mPlane Architecture Specification", April 2009 2015, . 2013 Authors' Addresses 2015 Brian Trammell (editor) 2016 ETH Zurich 2017 Gloriastrasse 35 2018 8092 Zurich 2019 Switzerland 2021 Email: ietf@trammell.ch 2023 Mirja Kuehlewind (editor) 2024 ETH Zurich 2025 Gloriastrasse 35 2026 8092 Zurich 2027 Switzerland 2029 Email: mirja.kuehlewind@tik.ee.ethz.ch