idnits 2.17.1 draft-ietf-ippm-twamp-yang-13.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 683 has weird spacing: '...riority uin...' == Line 717 has weird spacing: '...m-index uin...' -- The document date (July 2, 2018) is 2117 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-24) exists of draft-ietf-ippm-metric-registry-14 == Outdated reference: A later version (-04) exists of draft-ietf-ippm-port-twamp-test-01 -- Possible downref: Non-RFC (?) normative reference: ref. 'UML' -- Obsolete informational reference (is this intentional?): RFC 5246 (Obsoleted by RFC 8446) Summary: 0 errors (**), 0 flaws (~~), 5 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 IPPM WG R. Civil 3 Internet-Draft Ciena Corporation 4 Intended status: Standards Track A. Morton 5 Expires: January 3, 2019 AT&T Labs 6 R. Rahman 7 Cisco Systems 8 M. Jethanandani 9 Xoriant Corporation 10 K. Pentikousis, Ed. 11 Travelping 12 July 2, 2018 14 Two-Way Active Measurement Protocol (TWAMP) Data Model 15 draft-ietf-ippm-twamp-yang-13 17 Abstract 19 This document specifies a data model for client and server 20 implementations of the Two-Way Active Measurement Protocol (TWAMP). 21 The document defines the TWAMP data model through Unified Modeling 22 Language (UML) class diagrams and formally specifies it using a NDMA- 23 compliant YANG model. 25 Status of This Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at https://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on January 3, 2019. 42 Copyright Notice 44 Copyright (c) 2018 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (https://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 60 1.1. Motivation . . . . . . . . . . . . . . . . . . . . . . . 3 61 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 62 1.3. Document Organization . . . . . . . . . . . . . . . . . . 4 63 2. Scope, Model, and Applicability . . . . . . . . . . . . . . . 4 64 3. Data Model Overview . . . . . . . . . . . . . . . . . . . . . 5 65 3.1. Control-Client . . . . . . . . . . . . . . . . . . . . . 6 66 3.2. Server . . . . . . . . . . . . . . . . . . . . . . . . . 7 67 3.3. Session-Sender . . . . . . . . . . . . . . . . . . . . . 7 68 3.4. Session-Reflector . . . . . . . . . . . . . . . . . . . . 8 69 4. Data Model Parameters . . . . . . . . . . . . . . . . . . . . 8 70 4.1. Control-Client . . . . . . . . . . . . . . . . . . . . . 8 71 4.2. Server . . . . . . . . . . . . . . . . . . . . . . . . . 11 72 4.3. Session-Sender . . . . . . . . . . . . . . . . . . . . . 13 73 4.4. Session-Reflector . . . . . . . . . . . . . . . . . . . . 14 74 5. Data Model . . . . . . . . . . . . . . . . . . . . . . . . . 16 75 5.1. YANG Tree Diagram . . . . . . . . . . . . . . . . . . . . 16 76 5.2. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 19 77 6. Data Model Examples . . . . . . . . . . . . . . . . . . . . . 48 78 6.1. Control-Client . . . . . . . . . . . . . . . . . . . . . 48 79 6.2. Server . . . . . . . . . . . . . . . . . . . . . . . . . 50 80 6.3. Session-Sender . . . . . . . . . . . . . . . . . . . . . 51 81 6.4. Session-Reflector . . . . . . . . . . . . . . . . . . . . 52 82 7. Security Considerations . . . . . . . . . . . . . . . . . . . 55 83 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 56 84 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 57 85 10. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 57 86 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 57 87 11.1. Normative References . . . . . . . . . . . . . . . . . . 57 88 11.2. Informative References . . . . . . . . . . . . . . . . . 59 89 Appendix A. Detailed Data Model Examples . . . . . . . . . . . . 60 90 A.1. Control-Client . . . . . . . . . . . . . . . . . . . . . 60 91 A.2. Server . . . . . . . . . . . . . . . . . . . . . . . . . 62 92 A.3. Session-Sender . . . . . . . . . . . . . . . . . . . . . 64 93 A.4. Session-Reflector . . . . . . . . . . . . . . . . . . . . 65 94 Appendix B. TWAMP Operational Commands . . . . . . . . . . . . . 67 95 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 67 97 1. Introduction 99 The Two-Way Active Measurement Protocol (TWAMP) [RFC5357] is used to 100 measure network performance parameters such as latency, bandwidth, 101 and packet loss by sending probe packets and measuring their 102 experience in the network. To date, TWAMP implementations do not 103 come with a standard management framework, and, as such, implementers 104 have no choice except to provide a proprietary mechanism. This 105 document addresses this gap by defining the model using UML [UML] 106 class diagrams, and formally specifying a NMDA-complaint [RFC8342] 107 TWAMP data model using YANG 1.1 [RFC7950]. 109 1.1. Motivation 111 In current TWAMP deployments the lack of a standardized data model 112 limits the flexibility to dynamically instantiate TWAMP-based 113 measurements across equipment from different vendors. In large, 114 virtualized, and dynamically instantiated infrastructures where 115 network functions are placed according to orchestration algorithms, 116 proprietary mechanisms for managing TWAMP measurements pose severe 117 limitations with respect to programmability. 119 Two major trends call for standardizing TWAMP management aspects. 120 First, it is expected that in the coming years large-scale and multi- 121 vendor TWAMP deployments will become the norm. From an operations 122 perspective, using several vendor-specific TWAMP configuration 123 mechanisms when one standard mechanism could provide an alternative 124 is expensive and inefficient. Second, the increasingly software- 125 defined and virtualized nature of network infrastructures, based on 126 dynamic service chains [NSC] and programmable control and management 127 planes Software-Defined Networking (SDN): Layers and Architecture 128 Terminology [RFC7426] requires a well-defined data model for TWAMP 129 implementations. This document defines such a TWAMP data model and 130 specifies it formally using the YANG 1.1 [RFC7950] data modeling 131 language. 133 Note to RFC Editor: 135 Please replace the date 2018-07-02 in Section 5.2 of the draft with 136 the date of publication of this draft as a RFC. Also, replace 137 reference to RFC XXXX, and draft-ietf-ippm-port-twamp-test with the 138 RFC numbers assigned to the drafts. 140 1.2. Terminology 142 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 143 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 144 "OPTIONAL" in this document are to be interpreted as described in BCP 145 14 [RFC2119] [RFC8174] when, and only when, they appear in all 146 capitals, as shown here. 148 1.3. Document Organization 150 The rest of this document is organized as follows. Section 2 151 presents the scope and applicability of this document. Section 3 152 provides a high-level overview of the TWAMP data model. Section 4 153 details the configuration parameters of the data model and Section 5 154 specifies in YANG the TWAMP data model. Section 6 lists illustrative 155 examples which conform to the YANG data model specified in this 156 document. Appendix A elaborates these examples further. 158 2. Scope, Model, and Applicability 160 The purpose of this document is the specification of a vendor- 161 independent data model for TWAMP implementations. 163 Figure 1 illustrates a redrawn version of the TWAMP logical model 164 found in Section 1.2 of TWAMP [RFC5357]. The figure is annotated 165 with pointers to the UML [UML] diagrams provided in this document and 166 associated with the data model of the four logical entities in a 167 TWAMP deployment, namely the TWAMP Control-Client, Server, Session- 168 Sender and Session-Reflector. A UML [UML] Notation Guide is 169 available in Section 5 of the said document. 171 As per TWAMP [RFC5357], unlabeled links in Figure 1 are left 172 unspecified and may be proprietary protocols. 174 [Fig. 3] [Fig. 4] 175 +----------------+ +--------+ 176 | Control-Client | <-- TWAMP-Control --> | Server | 177 +----------------+ +--------+ 178 ^ ^ 179 | | 180 V V 181 +----------------+ +-------------------+ 182 | Session-Sender | <-- TWAMP-Test --> | Session-Reflector | 183 +----------------+ +-------------------+ 184 [Fig. 5] [Fig. 6] 186 Figure 1: Annotated TWAMP logical model 188 As per TWAMP [RFC5357], a TWAMP implementation may follow a 189 simplified logical model, in which the same node acts both as 190 Control-Client and Session-Sender, while another node acts at the 191 same time as TWAMP Server and Session-Reflector. Figure 2 192 illustrates this simplified logical model and indicates the 193 interaction between the TWAMP configuration client and server using, 194 for instance, NETCONF [RFC6241] or RESTCONF [RFC8040]. 196 o-------------------o o-------------------o 197 | Config client | | Config client | 198 o-------------------o o-------------------o 199 || || 200 NETCONF || RESTCONF NETCONF || RESTCONF 201 || || 202 o-------------------o o-------------------o 203 | Config server | | Config server | 204 | [Fig. 3, 5] | | [Fig. 4, 6] | 205 +-------------------+ +-------------------+ 206 | Control-Client | <-- TWAMP-Control --> | Server | 207 | | | | 208 | Session-Sender | <-- TWAMP-Test --> | Session-Reflector | 209 +-------------------+ +-------------------+ 211 Figure 2: Simplified TWAMP model and protocols 213 The data model defined in this document is orthogonal to the specific 214 protocol used between the Config client and Config server to 215 communicate the TWAMP configuration parameters. 217 Operational actions such as how TWAMP-Test sessions are started and 218 stopped, how performance measurement results are retrieved, or how 219 stored results are cleared, and so on, are not addressed by the 220 configuration model defined in this document. As noted above, such 221 operational actions are not part of the TWAMP specification TWAMP 222 [RFC5357] and hence are out of scope of this document. See also 223 Appendix B. In addition, for operational state, current work in 224 Registry for Performance Metrics [I-D.ietf-ippm-metric-registry], can 225 be used to develop an independent model for the performance metrics 226 that need to be captured and retrieved. 228 3. Data Model Overview 230 The TWAMP data model includes four categories of configuration items. 232 First, global configuration items relate to parameters that are set 233 on a per device level. For example, the administrative status of the 234 device with respect to whether it allows TWAMP sessions and, if so, 235 in what capacity (e.g. Control-Client, Server or both), is a typical 236 instance of a global configuration item. 238 A second category includes attributes that can be configured on a per 239 TWAMP-Control connection basis, such as the Server IP address. 241 A third category includes attributes related to per TWAMP-Test 242 session attributes, for instance setting different values in the 243 Differentiated Services Code Point (DSCP) field. 245 Finally, the data model includes attributes that relate to the 246 operational state of the TWAMP implementation. 248 As the TWAMP data model is described in the remaining sections of 249 this document, readers should keep in mind the functional entity 250 grouping illustrated in Figure 1. 252 3.1. Control-Client 254 A TWAMP Control-Client has an administrative status field set at the 255 device level that indicates whether the node is enabled to function 256 as such. 258 Each TWAMP Control-Client is associated with zero or more TWAMP- 259 Control connections. The main configuration parameters of each 260 control connection are: 262 o A name which can be used to uniquely identify at the Control- 263 Client a particular control connection. This name is necessary 264 for programmability reasons because at the time of creation of a 265 TWAMP-Control connection not all IP and TCP port number 266 information needed to uniquely identify the connection is 267 available. 269 o The IP address of the interface the Control-Client will use for 270 connections. 272 o The IP address of the remote TWAMP Server. 274 o Authentication and encryption attributes such as KeyID, Token and 275 the Client Initialization Vector (Client-IV); see also Section 3.1 276 in OWAMP [RFC4656] and Randomness Requirements for Security 277 [RFC4086]. 279 Each TWAMP-Control connection, in turn, is associated with zero or 280 more TWAMP-Test sessions. For each test session, the following 281 configuration items should be noted: 283 o The test session name uniquely identifies a particular test 284 session at the Control-Client and Session-Sender. Similar to the 285 control connections above, this unique test session name is needed 286 because at the time of creation of a TWAMP-Test session, for 287 example, the source UDP port number is not known to uniquely 288 identify the test session. 290 o The IP address and UDP port number of the Session-Sender on the 291 path under test by TWAMP. 293 o The IP address and UDP port number of the Session-Reflector on 294 said path. 296 o Information pertaining to the test packet stream, such as the test 297 starting time, which performance metric is to be used, as defined 298 in Registry for Performance Metrics 299 [I-D.ietf-ippm-metric-registry], or whether the test should be 300 repeated. 302 3.2. Server 304 Each TWAMP Server has an administrative status field set at the 305 device level to indicate whether the node is enabled to function as a 306 TWAMP Server. 308 Each Server is associated with zero or more TWAMP-Control 309 connections. Each control connection is uniquely identified by the 310 4-tuple {Control-Client IP address, Control-Client TCP port number, 311 Server IP address, Server TCP port}. Control connection configuration 312 items on a TWAMP Server are read-only. 314 3.3. Session-Sender 316 A TWAMP Session-Sender has an administrative status field set at the 317 device level that indicates whether the node is enabled to function 318 as such. 320 There is one Session-Sender instance for each TWAMP-Test session that 321 is initiated from the sending device. Primary configuration fields 322 include: 324 o The test session name MUST be identical to the corresponding test 325 session name on the TWAMP Control-Client (Section 3.1). 327 o The control connection name, which along with the test session 328 name uniquely identify the TWAMP Session-Sender instance. 330 o Information pertaining to the test packet stream, such as, the 331 number of test packets and the packet distribution to be employed; 332 see also Network performance measurement with periodic streams 333 [RFC3432]. 335 3.4. Session-Reflector 337 Each TWAMP Session-Reflector has an administrative status field set 338 at the device level to indicate whether the node is enabled to 339 function as such. 341 Each Session-Reflector is associated with zero or more TWAMP-Test 342 sessions. For each test session, the REFWAIT timeout parameter, 343 which determines whether to discontinue the session if no packets 344 have been received (TWAMP [RFC5357], Section 4.2), can be configured. 346 Read-only access to other data model parameters, such as the Sender 347 IP address, is foreseen. Each test session can be uniquely 348 identified by the 4-tuple mentioned in Section 3.2. 350 4. Data Model Parameters 352 This section defines the TWAMP data model using UML [UML] and 353 introduces selected parameters associated with the four TWAMP logical 354 entities. The complete TWAMP data model specification is provided in 355 the YANG module presented in Section 5.2. 357 4.1. Control-Client 359 The client container (see Figure 3) holds items that are related to 360 the configuration of the TWAMP Control-Client logical entity (recall 361 Figure 1). 363 The client container includes an administrative configuration 364 parameter (client/admin-state) that indicates whether the device is 365 allowed to initiate TWAMP-Control connections. 367 +-------------+ 368 | client | 369 +-------------+ 1..* +-----------------------+ 370 | admin-state |<>----------------------| mode-preference-chain | 371 | | +-----------------------+ 372 | | 1..* +------------+ | priority | 373 | |<>-----| key-chain | | mode | 374 +-------------+ +------------+ +-----------------------+ 375 ^ | key-id | 376 V | secret-key | 377 | +------------+ 378 | 0..* 379 +------------------------+ 380 | ctrl-connection | 381 +------------------------+ 382 | name | 383 | client-ip | 384 | server-ip | 385 | server-tcp-port | 0..* +----------------------+ 386 | control-packet-dscp |<>-------| test-session-request | 387 | key-id | +----------------------+ 388 | max-count | | name | 389 | client-tcp-port {ro} | | sender-ip | 390 | server-start-time {ro} | | sender-udp-port | 391 | state {ro} | | reflector-ip | 392 | selected-mode {ro} | | reflector-udp-port | 393 | token {ro} | | timeout | 394 | client-iv {ro} | | padding-length | 395 +------------------------+ | test-packet-dscp | 396 | start-time | 397 +-------------+ 1 | repeat | 398 | pm-reg-list |------<>| repeat-interval | 399 +-------------+ | state {ro} | 400 | pm-index | | sid {ro} | 401 +-------------+ +----------------------+ 403 Figure 3: TWAMP Control-Client UML class diagram 405 The client container holds a list (mode-preference-chain) which 406 specifies the Mode values according to their preferred order of use 407 by the operator of this Control-Client, including the authentication 408 and encryption Modes. Specifically, mode-preference-chain lists the 409 mode and its corresponding priority, as a 16-bit unsigned integer. 410 Values for the priority start with zero, the highest priority, and 411 decreasing priority value is indicated by every increase in value by 412 one. 414 Depending on the Modes available in the Server Greeting, the Control- 415 Client MUST choose the highest priority Mode from the configured 416 mode-preference-chain list. 418 Note that the list of preferred Modes may set multiple bit positions 419 independently, such as when referring to the extended TWAMP features 420 in Mixed Security Mode for TWAMP [RFC5618], Individual Session 421 Control Feature for TWAMP [RFC5938], TWAMP Reflect Octets and 422 Symmetrical Size Features [RFC6038], and IKEv2-Derived Shared Secret 423 Key for OWAMP and TWAMP [RFC7717]. If the Control-Client cannot 424 determine an acceptable Mode, or when the bit combinations do not 425 make sense, e.g., both authenticated and unauthenticated bit are set, 426 it MUST respond with zero Mode bits set in the Set-up Response 427 message, indicating it will not continue with the control connection. 429 In addition, the client container holds a list named key-chain which 430 relates key-id with the respective secret-key. Both the Server and 431 the Control-Client use the same mappings from key-id to secret-key 432 (in Figure 3); in order for this to work properly, key-id must be 433 unique across all systems in the administrative domain. The Server, 434 being prepared to conduct sessions with more than one Control-Client, 435 uses key-id to choose the appropriate secret-key; a Control-Client 436 would typically have different secret keys for different Servers. 437 The secret-key is the shared secret, of type binary and the length 438 SHOULD contain at least 128 bits of entropy. The key-id and secret- 439 key encoding SHOULD follow Section 9.8 of YANG [RFC7950]. The 440 derived key length (dkLen in PKCS #5: Password-Based Cryptography 441 Specification Version 2.1 [RFC8018]) MUST be 16 octets for the AES 442 Session-key used for encryption and 32 octets for the HMAC-SHA1 443 Session-key used for authentication; see also Section 6.10 of OWAMP 444 [RFC4656]. 446 Each client container also holds a list of control connections, where 447 each item in the list describes a TWAMP control connection initiated 448 by this Control-Client. There SHALL be one ctrl-connection per 449 TWAMP-Control (TCP) connection that is to be initiated from this 450 device. 452 In turn, each ctrl-connection holds a test-session-request list. 453 Each test-session-request holds information associated with the 454 Control-Client for this test session. This includes information 455 associated with the Request-TW-Session/Accept-Session message 456 exchange (see Section 3.5 of TWAMP [RFC5357]). 458 There SHALL be one instance of test-session-request for each TWAMP- 459 Test session that is to be negotiated by this TWAMP-Control 460 connection via a Request-TW-Session/Accept-Session exchange. 462 The Control-Client is also responsible for scheduling TWAMP-Test 463 sessions, therefore test-session-request holds information related to 464 these actions (e.g. pm-index, repeat-interval). 466 4.2. Server 468 The server container (see Figure 4) holds items that are related to 469 the configuration of the TWAMP Server logical entity (recall 470 Figure 1). 472 The server container includes an administrative configuration 473 parameter (server/admin-state) that indicates whether the device is 474 allowed to receive TWAMP-Control connections. 476 A device operating in the Server role cannot configure attributes on 477 a per TWAMP-Control connection basis, as it has no foreknowledge of 478 the incoming TWAMP-Control connections to be received. Consequently, 479 any parameter that the Server might want to apply to an incoming 480 control connection must be configured at the overall Server level and 481 applied to all incoming TWAMP-Control connections. 483 +---------------------+ 484 | server | 485 +---------------------+ 486 | admin-state | 1..* +------------+ 487 | server-tcp-port |<>------| key-chain | 488 | servwait | +------------+ 489 | control-packet-dscp | | key-id | 490 | count | | secret-key | 491 | max-count | +------------+ 492 | modes | 493 | | 0..* +--------------------------+ 494 | |<>------| ctrl-connection | 495 +---------------------+ +--------------------------+ 496 | client-ip {ro} | 497 | client-tcp-port {ro} | 498 | server-ip {ro} | 499 | server-tcp-port {ro} | 500 | state {ro} | 501 | control-packet-dscp {ro} | 502 | selected-mode {ro} | 503 | key-id {ro} | 504 | count {ro} | 505 | max-count {ro} | 506 | salt {ro} | 507 | server-iv {ro} | 508 | challenge {ro} | 509 +--------------------------+ 511 Figure 4: TWAMP Server UML class diagram 513 Each server container holds a list named key-chain which relates key- 514 id with the respective secret-key. As mentioned in Section 4.1, both 515 the Server and the Control-Client use the same mapping from key-id to 516 shared secret-key; in order for this to work properly, key-id must be 517 unique across all the systems in the administrative domain. The 518 Server, being prepared to conduct sessions with more than one 519 Control-Client, uses key-id to choose the appropriate secret-key; a 520 Control-Client would typically have different secret keys for 521 different Servers. The key-id tells the Server which shared secret- 522 key the Control-Client wishes to use for authentication or 523 encryption. 525 Each incoming control connection active on the Server is represented 526 by a ctrl-connection. There SHALL be one ctrl-connection per 527 incoming TWAMP-Control (TCP) connection that is received and active 528 on the Server. Each ctrl-connection can be uniquely identified by 529 the 4-tuple {client-ip, client-tcp-port, server-ip, server-tcp-port}. 530 All items in the ctrl-connection list are read-only. 532 4.3. Session-Sender 534 The session-sender container, illustrated in Figure 5, holds items 535 that are related to the configuration of the TWAMP Session-Sender 536 logical entity. 538 The session-sender container includes an administrative parameter 539 (session-sender/admin-state) that controls whether the device is 540 allowed to initiate TWAMP-Test sessions. 542 +----------------+ 543 | session-sender | 544 +----------------+ 0..* +---------------------------+ 545 | admin-state |<>-----| test-session | 546 +----------------+ +---------------------------+ 547 | name | 548 | ctrl-connection-name {ro} | 549 | fill-mode | 550 | number-of-packets | 551 | state {ro} | 552 | sent-packets {ro} | 553 | rcv-packets {ro} | 554 | last-sent-seq {ro} | 555 | last-rcv-seq {ro} | 556 +---------------------------+ 557 ^ 558 V 559 | 1 560 +---------------------+ 561 | packet-distribution | 562 +---------------------+ 563 | periodic / poisson | 564 +---------------------+ 565 | | 566 +-------------------+ | 567 | periodic-interval | | 568 +-------------------+ | 569 | 570 +--------------+ 571 | lambda | 572 | max-interval | 573 +--------------+ 575 Figure 5: TWAMP Session-Sender UML class diagram 577 Each TWAMP-Test session initiated by the Session-Sender will be 578 represented by an instance of a test-session object. There SHALL be 579 one instance of test-session for each TWAMP-Test session for which 580 packets are being sent. 582 4.4. Session-Reflector 584 The session-reflector container, illustrated in Figure 6, holds items 585 that are related to the configuration of the TWAMP Session-Reflector 586 logical entity. 588 The session-reflector container includes an administrative parameter 589 (session-reflector/admin-state) that controls whether the device is 590 allowed to respond to incoming TWAMP-Test sessions. 592 A device operating in the Session-Reflector role cannot configure 593 attributes on a per-session basis, as it has no foreknowledge of what 594 incoming sessions it will receive. As such, any parameter that the 595 Session-Reflector might want to apply to an incoming TWAMP-Test 596 session must be configured at the overall Session-Reflector level and 597 are applied to all incoming sessions. 599 +-------------------+ 600 | session-reflector | 601 +-------------------+ 602 | admin-state | 603 | refwait | 604 +-------------------+ 605 ^ 606 V 607 | 608 | 0..* 609 +----------------------------------------+ 610 | test-session | 611 +----------------------------------------+ 612 | sid {ro} | 613 | sender-ip {ro} | 614 | sender-udp-port {ro} | 615 | reflector-ip {ro} | 616 | reflector-udp-port {ro} | 617 | parent-connection-client-ip {ro} | 618 | parent-connection-client-tcp-port {ro} | 619 | parent-connection-server-ip {ro} | 620 | parent-connection-server-tcp-port {ro} | 621 | test-packet-dscp {ro} | 622 | sent-packets {ro} | 623 | rcv-packets {ro} | 624 | last-sent-seq {ro} | 625 | last-rcv-seq {ro} | 626 +----------------------------------------+ 628 Figure 6: TWAMP Session-Reflector UML class diagram 630 Each incoming TWAMP-Test session that is active on the Session- 631 Reflector SHALL be represented by an instance of a test-session 632 object. All items in the test-session object are read-only. 634 Instances of test-session are indexed by a session identifier (sid). 635 This value is auto-allocated by the TWAMP Server as test session 636 requests are received, and communicated back to the Control-Client in 637 the SID field of the Accept-Session message; see Section 4.3 of TWAMP 638 Reflect Octets and Symmetrical Size Features [RFC6038]. 640 When attempting to retrieve operational data for active test sessions 641 from a Session-Reflector device, the user will not know what sessions 642 are currently active on that device, or what SIDs have been auto- 643 allocated for these test sessions. If the user has network access to 644 the Control-Client device, then it is possible to read the data for 645 this session under client/ctrl-connection/test-session-request/sid 646 and obtain the SID (see Figure 3). The user may then use this SID 647 value as an index to retrieve an individual session-reflector/test- 648 session instance on the Session-Reflector device. 650 If the user has no network access to the Control-Client device, then 651 the only option is to retrieve all test-session instances from the 652 Session-Reflector device, and then pick out specific test-session 653 instances of interest to the user. This could be problematic if a 654 large number of test sessions are currently active on that device. 656 Each Session-Reflector TWAMP-Test session contains the following 657 4-tuple: {parent-connection-client-ip, parent-connection-client-tcp- 658 port, parent-connection-server-ip, parent-connection-server-tcp- 659 port}. This 4-tuple MUST correspond to the equivalent 4-tuple 660 {client-ip, client-tcp-port, server-ip, server-tcp-port} in server/ 661 ctrl-connection. This 4-tuple allows the user to trace back from the 662 TWAMP-Test session to the (parent) TWAMP-Control connection that 663 negotiated this test session. 665 5. Data Model 667 This section formally specifies the TWAMP data model using YANG. 669 5.1. YANG Tree Diagram 671 This section presents a simplified graphical representation of the 672 TWAMP data model using a YANG tree diagram. Readers should keep in 673 mind that the limit of 72 characters per line forces us to introduce 674 artificial line breaks in some tree diagram nodes. Tree diagrams 675 used in this document follow the notation defined in YANG Tree 676 Diagrams [RFC8340]. 678 module: ietf-twamp 679 +--rw twamp 680 +--rw client {control-client}? 681 | +--rw admin-state? boolean 682 | +--rw mode-preference-chain* [priority] 683 | | +--rw priority uint16 684 | | +--rw mode? twamp-modes 685 | +--rw key-chain* [key-id] 686 | | +--rw key-id string 687 | | +--rw secret-key? binary 688 | +--rw ctrl-connection* [name] 689 | +--rw name string 690 | +--rw client-ip? inet:ip-address 691 | +--rw server-ip inet:ip-address 692 | +--rw server-tcp-port? inet:port-number 693 | +--rw control-packet-dscp? inet:dscp 694 | +--rw key-id? string 695 | +--rw max-count-exponent? uint8 696 | +--ro client-tcp-port? inet:port-number 697 | +--ro server-start-time? uint64 698 | +--ro repeat-count? uint64 699 | +--ro state? 700 | | control-client-connection-state 701 | +--ro selected-mode? twamp-modes 702 | +--ro token? binary 703 | +--ro client-iv? binary 704 | +--rw test-session-request* [name] 705 | +--rw name string 706 | +--rw sender-ip? inet:ip-address 707 | +--rw sender-udp-port? union 708 | +--rw reflector-ip inet:ip-address 709 | +--rw reflector-udp-port? inet:port-number 710 | +--rw timeout? uint64 711 | +--rw padding-length? uint32 712 | +--rw test-packet-dscp? inet:dscp 713 | +--rw start-time? uint64 714 | +--rw repeat? uint32 715 | +--rw repeat-interval? uint32 716 | +--rw pm-reg-list* [pm-index] 717 | | +--rw pm-index uint16 718 | +--ro state? test-session-state 719 | +--ro sid? string 720 +--rw server {server}? 721 | +--rw admin-state? boolean 722 | +--rw server-tcp-port? inet:port-number 723 | +--rw servwait? uint32 724 | +--rw control-packet-dscp? inet:dscp 725 | +--rw count? uint8 726 | +--rw max-count-exponent? uint8 727 | +--rw modes? twamp-modes 728 | +--rw key-chain* [key-id] 729 | | +--rw key-id string 730 | | +--rw secret-key? binary 731 | +--ro ctrl-connection* 732 | [client-ip client-tcp-port server-ip server-tcp-port] 733 | +--ro client-ip inet:ip-address 734 | +--ro client-tcp-port inet:port-number 735 | +--ro server-ip inet:ip-address 736 | +--ro server-tcp-port inet:port-number 737 | +--ro state? server-ctrl-connection-state 738 | +--ro control-packet-dscp? inet:dscp 739 | +--ro selected-mode? twamp-modes 740 | +--ro key-id? string 741 | +--ro count? uint8 742 | +--ro max-count-exponent? uint8 743 | +--ro salt? binary 744 | +--ro server-iv? binary 745 | +--ro challenge? binary 746 +--rw session-sender {session-sender}? 747 | +--rw admin-state? boolean 748 | +--rw test-session* [name] 749 | +--rw name string 750 | +--ro ctrl-connection-name? string 751 | +--rw fill-mode? padding-fill-mode 752 | +--rw number-of-packets uint32 753 | +--rw (packet-distribution)? 754 | | +--:(periodic) 755 | | | +--rw periodic-interval decimal64 756 | | +--:(poisson) 757 | | +--rw lambda decimal64 758 | | +--rw max-interval? decimal64 759 | +--ro state? sender-session-state 760 | +--ro sent-packets? uint32 761 | +--ro rcv-packets? uint32 762 | +--ro last-sent-seq? uint32 763 | +--ro last-rcv-seq? uint32 764 +--rw session-reflector {session-reflector}? 765 +--rw admin-state? boolean 766 +--rw refwait? uint32 767 +--ro test-session* 768 [sender-ip sender-udp-port reflector-ip reflector-udp 769 -port] 770 +--ro sid? string 771 +--ro sender-ip inet:ip-address 772 +--ro sender-udp-port 773 | dynamic-port-number 774 +--ro reflector-ip inet:ip-address 775 +--ro reflector-udp-port inet:port-numbe 776 r 777 +--ro parent-connection-client-ip? inet:ip-address 778 +--ro parent-connection-client-tcp-port? inet:port-numbe 779 r 780 +--ro parent-connection-server-ip? inet:ip-address 781 +--ro parent-connection-server-tcp-port? inet:port-numbe 782 r 783 +--ro test-packet-dscp? inet:dscp 784 +--ro sent-packets? uint32 785 +--ro rcv-packets? uint32 786 +--ro last-sent-seq? uint32 787 +--ro last-rcv-seq? uint32 789 Figure 7: YANG Tree Diagram. 791 5.2. YANG Module 793 This section presents the YANG module for the TWAMP data model 794 defined in this document. The module imports definitions from Common 795 YANG Data Types [RFC6991], and references NTPv4 Specification 796 [RFC5905], Framework for IP Performance Metrics [RFC2330], Randomness 797 Requirements for Security [RFC4086], OWAMP [RFC4656], TWAMP 798 [RFC5357], More Features for TWAMP [RFC5618], Individual Session 799 Control Feature [RFC5938], TWAMP Reflect Octets and Symmetrical Size 800 Features [RFC6038], Advances Stream and Sampling Framework [RFC7312], 801 IKEv2-Derived Shared Secret Key for OWAMP and TWAMP [RFC7717], and 802 OWAMP and TWAMP Well-Known Port Assignments 803 [I-D.ietf-ippm-port-twamp-test]. 805 file "ietf-twamp@2018-07-02.yang" 807 module ietf-twamp { 808 yang-version 1.1; 809 namespace urn:ietf:params:xml:ns:yang:ietf-twamp; 810 prefix ietf-twamp; 812 import ietf-inet-types { 813 prefix inet; 814 reference 815 "RFC 6991: Common YANG Types."; 816 } 818 organization 819 "IETF IPPM (IP Performance Metrics) Working Group"; 821 contact 822 "WG Web: http://tools.ietf.org/wg/ippm/ 823 WG List: ippm@ietf.org 825 Editor: Ruth Civil 826 gcivil@ciena.com 827 Editor: Al Morton 828 acmorton@att.com 829 Editor: Reshad Rehman 830 rrahman@cisco.com 831 Editor: Mahesh Jethanandani 832 mjethanandani@gmail.com 833 Editor: Kostas Pentikousis 834 k.pentikousis@travelping.com"; 836 description 837 "This YANG module specifies a vendor-independent data 838 model for the Two-Way Active Measurement Protocol (TWAMP). 840 The data model covers four TWAMP logical entities, namely, 841 Control-Client, Server, Session-Sender, and Session-Reflector, 842 as illustrated in the annotated TWAMP logical model (Fig. 1 843 of RFC XXXX). 845 This YANG module uses features to indicate which of the four 846 logical entities are supported by a TWAMP implementation. 848 Copyright (c) 2018 IETF Trust and the persons identified as 849 the document authors. All rights reserved. 850 Redistribution and use in source and binary forms, with or 851 without modification, is permitted pursuant to, and subject 852 to the license terms contained in, the Simplified BSD 853 License set forth in Section 4.c of the IETF Trust's Legal 854 Provisions Relating to IETF Documents 855 (http://trustee.ietf.org/license-info). 857 This version of this YANG module is part of RFC XXXX; see 858 the RFC itself for full legal notices."; 860 revision 2018-07-02 { 861 description 862 "Initial Revision. 864 Covers RFC 5357, RFC 5618, RFC 5938, RFC 6038, RFC 7717, and 865 draft-ietf-ippm-metric-registry"; 867 reference 868 "RFC XXXX: TWAMP YANG Data Model."; 869 } 871 /* 872 * Typedefs 873 */ 875 typedef twamp-modes { 876 type bits { 877 bit unauthenticated { 878 position 0; 879 description 880 "Unauthenticated mode, in which no encryption or 881 authentication is applied in TWAMP-Control and 882 TWAMP-Test. KeyID, Token, and Client-IV are not used in 883 the Set-Up-Response message. See Section 3.1 of 884 RFC 4656."; 886 reference 887 "RFC 4656: A One-way Active Measurement Protocol 888 (OWAMP)"; 889 } 890 bit authenticated { 891 position 1; 892 description 893 "Authenticated mode, in which the Control-Client and 894 Server possess a shared secret thus prohibiting 895 'theft of service'. As per Section 6 of RFC 4656, 896 in 'authenticated mode, the timestamp is in the clear 897 and is not protected cryptographically in any way, 898 while the rest of the message has the same protection 899 as in encrypted mode. This mode allows one to trade off 900 cryptographic protection against accuracy of 901 timestamps.'"; 902 reference 903 "RFC 4656: A One-way Active Measurement Protocol 904 (OWAMP)"; 905 } 906 bit encrypted { 907 position 2; 908 description 909 "Encrypted mode 'makes it impossible to alter 910 timestamps undetectably' [Section 6 of RFC 4656]. 911 See also Section 4 of RFC 7717."; 912 reference 913 "RFC 4656: A One-way Active Measurement Protocol 914 (OWAMP)"; 915 } 916 bit unauth-test-encrpyt-control { 917 position 3; 918 description 919 "When using the Mixed Security Mode, the TWAMP-Test 920 protocol follows the Unauthenticated mode and the 921 TWAMP-Control protocol the Encrypted mode."; 922 reference 923 "RFC 5618: Mixed Security Mode for the Two-Way Active 924 Measurement Protocol (TWAMP)"; 925 } 926 bit individual-session-control { 927 position 4; 928 description 929 "This mode enables individual test sessions using 930 Session Identifiers."; 931 reference 932 "RFC 5938: Individual Session Control Feature 933 for the Two-Way Active Measurement Protocol (TWAMP)"; 935 } 936 bit reflect-octets { 937 position 5; 938 description 939 "This mode indicates the reflect octets capability."; 940 reference 941 "RFC 6038: Two-Way Active Measurement Protocol (TWAMP) 942 Reflect Octets and Symmetrical Size Features"; 943 } 944 bit symmetrical-size { 945 position 6; 946 description 947 "This mode indicates support for the symmetrical size 948 sender test packet format."; 949 reference 950 "RFC 6038: Two-Way Active Measurement Protocol (TWAMP) 951 Reflect Octets and Symmetrical Size Features"; 952 } 953 bit IKEv2Derived { 954 position 7; 955 description 956 "In this mode the the shared key is derived 957 from an IKEv2 security association (SA)."; 958 reference 959 "RFC 7717: IKEv2-Derived Shared Secret Key for 960 the One-Way Active Measurement Protocol (OWAMP) 961 and Two-Way Active Measurement Protocol (TWAMP)"; 962 } 963 } 964 description 965 "Specifies the configurable TWAMP-Modes supported during a 966 TWAMP-Control Connection setup between a Control-Client 967 and a Server. Section 7 of RFC 7717 summarizes the 968 TWAMP-Modes registry and points to their formal 969 specification."; 970 } 972 typedef control-client-connection-state { 973 type enumeration { 974 enum active { 975 description 976 "Indicates an active TWAMP-Control connection to 977 Server."; 978 } 979 enum idle { 980 description 981 "Indicates an idle TWAMP-Control connection to Server."; 982 } 984 } 985 description 986 "Indicates the Control-Client TWAMP-Control connection 987 state."; 988 } 990 typedef test-session-state { 991 type enumeration { 992 enum accepted { 993 value 0; 994 description 995 "Indicates an accepted TWAMP-Test session request."; 996 } 997 enum failed { 998 value 1; 999 description 1000 "Indicates a TWAMP-Test session failure due to 1001 some unspecified reason (catch-all)."; 1002 } 1003 enum internal-error { 1004 value 2; 1005 description 1006 "Indicates a TWAMP-Test session failure due to 1007 an internal error."; 1008 } 1009 enum not-supported { 1010 value 3; 1011 description 1012 "Indicates a TWAMP-Test session failure because 1013 some aspect of the TWAMP-Test session request 1014 is not supported."; 1015 } 1016 enum permanent-resource-limit { 1017 value 4; 1018 description 1019 "Indicates a TWAMP-Test session failure due to 1020 permanent resource limitations."; 1021 } 1022 enum temp-resource-limit { 1023 value 5; 1024 description 1025 "Indicates a TWAMP-Test session failure due to 1026 temporary resource limitations."; 1027 } 1028 } 1029 description 1030 "Indicates the Control-Client TWAMP-Test session state."; 1031 } 1032 typedef server-ctrl-connection-state { 1033 type enumeration { 1034 enum active { 1035 description 1036 "Indicates an active TWAMP-Control connection 1037 to the Control-Client."; 1038 } 1039 enum servwait { 1040 description 1041 "Indicates that the TWAMP-Control connection to the 1042 Control-Client is in SERVWAIT as per the definition of 1043 Section 3.1 of RFC 5357."; 1044 } 1045 } 1046 description 1047 "Indicates the Server TWAMP-Control connection state."; 1048 } 1050 typedef sender-session-state { 1051 type enumeration { 1052 enum active { 1053 description 1054 "Indicates that the TWAMP-Test session is active."; 1055 } 1056 enum failure { 1057 description 1058 "Indicates that the TWAMP-Test session has failed."; 1059 } 1060 } 1061 description 1062 "Indicates the Session-Sender TWAMP-Test session state."; 1063 } 1065 typedef padding-fill-mode { 1066 type enumeration { 1067 enum zero { 1068 description 1069 "TWAMP-Test packets are padded with all zeros."; 1070 } 1071 enum random { 1072 description 1073 "TWAMP-Test packets are padded with pseudo-random 1074 numbers."; 1075 } 1076 } 1077 description 1078 "Indicates what type of packet padding is used in the 1079 TWAMP-Test packets."; 1081 } 1083 typedef dynamic-port-number { 1084 type inet:port-number { 1085 range 49152..65535; 1086 } 1087 description "Dynamic range for port numbers."; 1088 } 1090 /* 1091 * Features 1092 */ 1094 feature control-client { 1095 description 1096 "Indicates that the device supports configuration of the 1097 TWAMP Control-Client logical entity."; 1098 } 1100 feature server { 1101 description 1102 "Indicates that the device supports configuration of the 1103 TWAMP Server logical entity."; 1104 } 1106 feature session-sender { 1107 description 1108 "Indicates that the device supports configuration of the 1109 TWAMP Session-Sender logical entity."; 1110 } 1112 feature session-reflector { 1113 description 1114 "Indicates that the device supports configuration of the 1115 TWAMP Session-Reflector logical entity."; 1116 } 1118 /* 1119 * Reusable node groups 1120 */ 1122 grouping key-management { 1123 list key-chain { 1124 key key-id; 1125 leaf key-id { 1126 type string { 1127 length 1..80; 1129 } 1130 description 1131 "KeyID used for a TWAMP-Control connection. As per 1132 Section 3.1 of RFC 4656, KeyID is 'a UTF-8 string, up to 1133 80 octets in length' and is used to select which 'shared 1134 shared secret the [Control-Client] wishes to use to 1135 authenticate or encrypt'."; 1136 } 1137 leaf secret-key { 1138 type binary; 1139 description 1140 "The secret key corresponding to the KeyID for this 1141 TWAMP-Control connection."; 1142 } 1143 description 1144 "Relates KeyIDs with their respective secret keys 1145 in a TWAMP-Control connection."; 1146 } 1147 description 1148 "Used by the Control-Client and Server for TWAMP-Control 1149 key management."; 1150 } 1152 grouping maintenance-statistics { 1153 leaf sent-packets { 1154 type uint32; 1155 config false; 1156 description 1157 "Indicates the number of packets sent."; 1158 } 1160 leaf rcv-packets { 1161 type uint32; 1162 config false; 1163 description 1164 "Indicates the number of packets received."; 1165 } 1167 leaf last-sent-seq { 1168 type uint32; 1169 config false; 1170 description 1171 "Indicates the last sent sequence number."; 1172 } 1174 leaf last-rcv-seq { 1175 type uint32; 1176 config false; 1177 description 1178 "Indicates the last received sequence number."; 1179 } 1180 description 1181 "Used for TWAMP-Test maintenance statistics."; 1182 } 1184 grouping count { 1185 leaf count { 1186 type uint8 { 1187 range "10..31"; 1188 } 1189 default 15; 1190 description 1191 "Parameter communicated to the Control-Client as part of 1192 the Server Greeting message and used for deriving a key 1193 from a shared secret as per Section 3.1 of RFC 4656: 1194 MUST be a power of 2 and at least 1024. It is configured 1195 by providing said power. For example, configuring 20 here 1196 means count 2^20 = 1048576. The default is 15, 1197 meaning 2^15 = 32768."; 1198 } 1199 description 1200 "Reusable data structure for count, which is used both in the 1201 Server and the Control-Client."; 1202 } 1204 grouping max-count-exponent { 1205 leaf max-count-exponent { 1206 type uint8 { 1207 range 10..31; 1208 } 1209 default 20; 1210 description 1211 "This parameter limits the maximum Count value, which MUST 1212 be a power of 2 and at least 1024 as per RFC 5357. It is 1213 configured by providing said power. For example, 1214 configuring 10 here means max count 2^10 = 1024. 1215 The default is 20, meaning 2^20 = 1048576. 1217 A TWAMP Server uses this configured value in the 1218 Server-Greeting message sent to the Control-Client. 1220 A TWAMP Control-Client uses this configured value to 1221 prevent denial-of-service (DOS) attacks by closing the 1222 control connection to the Server if it 'receives a 1223 Server-Greeting message with Count greater that its 1224 maximum configured value', as per Section 6 of RFC 5357. 1226 Further, note that according to Section 6 of RFC 5357: 1228 'If an attacking system sets the maximum value in 1229 Count (2**32), then the system under attack would stall 1230 for a significant period of time while it attempts to 1231 generate keys. 1233 TWAMP-compliant systems SHOULD have a configuration 1234 control to limit the maximum count value. The default 1235 max-count-exponent value SHOULD be 15 which corresponds 1236 to a maximum value of 2**15 or 32768.' 1238 RFC 5357 does not qualify 'significant period' in terms of 1239 time, but it is clear that this depends on the processing 1240 capacity available and operators need to pay attention to 1241 this security consideration."; 1242 } 1243 description 1244 "Reusable data structure for max-count which is used both at 1245 the Control-Client and the Server containers."; 1246 } 1248 /* 1249 * Configuration data nodes 1250 */ 1252 container twamp { 1253 description 1254 "TWAMP logical entity configuration grouping of four models 1255 which correspond to the four TWAMP logical entities 1256 Control-Client, Server, Session-Sender, and Session-Reflector 1257 as illustrated in Fig. 1 of RFC XXXX."; 1259 container client { 1260 if-feature control-client; 1261 description 1262 "Configuration of the TWAMP Control-Client logical 1263 entity."; 1265 leaf admin-state { 1266 type boolean; 1267 default true; 1268 description 1269 "Indicates whether the device is allowed to operate as a 1270 TWAMP Control-Client."; 1271 } 1272 list mode-preference-chain { 1273 key priority; 1274 unique mode; 1275 leaf priority { 1276 type uint16; 1277 description 1278 "Indicates the Control-Client Mode preference priority 1279 expressed as a 16-bit unsigned integer. Values for the 1280 priority start with zero, the highest priority, and 1281 decreasing priority value is indicated by every increase 1282 in value by one."; 1283 } 1284 leaf mode { 1285 type twamp-modes; 1286 description 1287 "The supported TWAMP Mode matching the corresponding 1288 priority."; 1290 } 1291 description 1292 "Indicates the Control-Client preferred order of use of 1293 the supported TWAMP Modes. 1295 Depending on the Modes available in the TWAMP Server 1296 Greeting message (see Fig. 2 of RFC 7717), the 1297 Control-Client MUST choose the highest priority 1298 Mode from the configured mode-preference-chain list."; 1299 } 1301 uses key-management; 1303 list ctrl-connection { 1304 key name; 1305 description 1306 "List of TWAMP Control-Client control connections. 1307 Each item in the list describes a control connection 1308 that will be initiated by this Control-Client"; 1310 leaf name { 1311 type string; 1312 description 1313 "A unique name used as a key to identify this 1314 individual TWAMP-Control connection on the 1315 Control-Client device."; 1316 } 1317 leaf client-ip { 1318 type inet:ip-address; 1319 description 1320 "The IP address of the local Control-Client device, 1321 to be placed in the source IP address field of the 1322 IP header in TWAMP-Control (TCP) packets belonging 1323 to this control connection. If not configured, the 1324 device SHALL choose its own source IP address."; 1325 } 1326 leaf server-ip { 1327 type inet:ip-address; 1328 mandatory true; 1329 description 1330 "The IP address of the remote Server device, which the 1331 TWAMP-Control connection will be initiated to."; 1332 } 1334 leaf server-tcp-port { 1335 type inet:port-number; 1336 default 862; 1337 description 1338 "This parameter defines the TCP port number that is 1339 to be used by this outgoing TWAMP-Control connection. 1340 Typically, this is the well-known TWAMP-Control 1341 port number (862) as per RFC 5357 However, there are 1342 known realizations of TWAMP in the field that were 1343 implemented before this well-known port number was 1344 allocated. These early implementations allowed the 1345 port number to be configured. This parameter is 1346 therefore provided for backward compatibility 1347 reasons."; 1348 } 1350 leaf control-packet-dscp { 1351 type inet:dscp; 1352 default 0; 1353 description 1354 "The DSCP value to be placed in the IP header of 1355 TWAMP-Control (TCP) packets generated by this 1356 Control-Client."; 1357 } 1359 leaf key-id { 1360 type string { 1361 length 1..80; 1362 } 1363 description 1364 "Indicates the KeyID value selected for this 1365 TWAMP-Control connection."; 1366 } 1367 uses max-count-exponent; 1369 leaf client-tcp-port { 1370 type inet:port-number; 1371 config false; 1372 description 1373 "Indicates the source TCP port number used in the 1374 TWAMP-Control packets belonging to this control 1375 connection."; 1376 } 1378 leaf server-start-time { 1379 type uint64; 1380 config false; 1381 description 1382 "Indicates the Start-Time advertised by the Server in 1383 the Server-Start message (RFC 4656, Section 3.1), 1384 representing the time when the current 1385 instantiation of the Server started operating. 1386 The timestamp format follows RFC 5905 1387 according to Section 4.1.2 of RFC 4656."; 1388 reference 1389 "RFC 4656: OWAMP, Section 3.1 and 4.1.2, 1390 RFC 5905: NTPv4 Specification."; 1391 } 1393 leaf repeat-count { 1394 type uint64; 1395 config false; 1396 description 1397 "Indicates how many times the test session has been 1398 repeated. When a test is running, this value will be 1399 greater than 0. If the repeat parameter is non-zero, 1400 this value is smaller than or equal to the repeat 1401 parameter."; 1402 } 1403 leaf state { 1404 type control-client-connection-state; 1405 config false; 1406 description 1407 "Indicates the current state of the TWAMP-Control 1408 connection state."; 1409 } 1411 leaf selected-mode { 1412 type twamp-modes; 1413 config false; 1414 description 1415 "The TWAMP Mode that the Control-Client has chosen for 1416 this control connection as set in the Mode field of 1417 the Set-Up-Response message"; 1418 reference 1419 "RFC 4656, Section 3.1."; 1420 } 1422 leaf token { 1423 type binary { 1424 length 64; 1425 } 1426 config false; 1427 description 1428 "This parameter holds the 64 octets containing the 1429 concatenation of a 16-octet Challenge, a 16-octet AES 1430 Session-key used for encryption, and a 32-octet 1431 HMAC-SHA1 Session-key used for authentication; see 1432 also the last paragraph of Section 6 in RFC 4656. 1434 If the Mode defined in RFC 7717 is selected 1435 (selected-mode), Token is limited to 16 octets."; 1436 reference 1437 "RFC 4086: Randomness Requirements for Security 1439 RFC 7717: IKEv2-Derived Shared Secret Key for the 1440 One-Way Active Measurement Protocol (OWAMP) and 1441 Two-Way Active Measurement Protocol (TWAMP)"; 1442 } 1444 leaf client-iv { 1445 type binary { 1446 length 16; 1447 } 1448 config false; 1449 description 1450 "Indicates the Control-Client Initialization Vector 1451 (Client-IV), that is generated randomly by the 1452 Control-Client. As per RFC 4656: 1454 Client-IV merely needs to be unique (i.e., it MUST 1455 never be repeated for different sessions using the 1456 same secret key; a simple way to achieve that without 1457 the use of cumbersome state is to generate the 1458 Client-IV values using a cryptographically secure 1459 pseudo-random number source. 1461 If the Mode defined in RFC 7717 is selected 1462 (selected-mode), Client-IV is limited to 12 octets."; 1464 reference 1465 "RFC 4656: A One-way Active Measurement Protocol 1466 (OWAMP). 1468 RFC 7717: IKEv2-Derived Shared Secret Key for the 1469 One-Way Active Measurement Protocol (OWAMP) and 1470 Two-Way Active Measurement Protocol (TWAMP)"; 1471 } 1473 list test-session-request { 1474 key name; 1475 description 1476 "Information associated with the Control-Client 1477 for this test session"; 1479 leaf name { 1480 type string; 1481 description 1482 "A unique name to be used for identification of 1483 this TWAMP-Test session on the Control-Client."; 1484 } 1486 leaf sender-ip { 1487 type inet:ip-address; 1488 description 1489 "The IP address of the Session-Sender device, 1490 which is to be placed in the source IP address 1491 field of the IP header in TWAMP-Test (UDP) packets 1492 belonging to this test session. This value will be 1493 used to populate the sender address field of the 1494 Request-TW-Session message. 1496 If not configured, the device SHALL choose its own 1497 source IP address."; 1498 } 1500 leaf sender-udp-port { 1501 type union { 1502 type dynamic-port-number; 1503 type enumeration { 1504 enum autoallocate { 1505 description 1506 "Indicates that the Contol-Client will 1507 auto-allocate the TWAMP-Test (UDP) port number 1508 from the dynamic port range."; 1509 } 1510 } 1511 } 1512 default autoallocate; 1513 description 1514 "The UDP port number that is to be used by 1515 the Session-Sender for this TWAMP-Test session. 1516 The number is restricted to the dynamic port range. 1518 By default the Control-Client SHALL auto-allocate a 1519 UDP port number for this TWAMP-Test session. 1521 The configured (or auto-allocated) value is 1522 advertised in the Sender Port field of the 1523 Request-TW-session message (see Section 3.5 of 1524 RFC 5357). Note that in the scenario where a device 1525 auto-allocates a UDP port number for a session, and 1526 the repeat parameter for that session indicates that 1527 it should be repeated, the device is free to 1528 auto-allocate a different UDP port number when it 1529 negotiates the next (repeated) iteration of this 1530 session."; 1531 } 1533 leaf reflector-ip { 1534 type inet:ip-address; 1535 mandatory true; 1536 description 1537 "The IP address belonging to the remote 1538 Session-Reflector device to which the TWAMP-Test 1539 session will be initiated. This value will be 1540 used to populate the receiver address field of 1541 the Request-TW-Session message."; 1542 } 1544 leaf reflector-udp-port { 1545 type inet:port-number { 1546 range "862 | 49152..65535"; 1547 } 1548 description 1549 "This parameter defines the UDP port number that 1550 will be used by the Session-Reflector for 1551 this TWAMP-Test session. The default number is 1552 within the dynamic port range and is to be placed 1553 in the Receiver Port field of the Request-TW-Session 1554 message. The well-known port (862) MAY be 1555 used."; 1556 reference 1557 "draft-ietf-ippm-port-twamp-test: OWAMP and TWAMP 1558 Well-Known Port Assignments."; 1559 } 1560 leaf timeout { 1561 type uint64; 1562 units seconds; 1563 default 2; 1564 description 1565 "The length of time (in seconds) that the 1566 Session-Reflector should continue to respond to 1567 packets belonging to this TWAMP-Test session after 1568 a Stop-Sessions TWAMP-Control message has been 1569 received. 1571 This value will be placed in the Timeout field of 1572 the Request-TW-Session message."; 1573 reference 1574 "RFC 5357: TWAMP, Section 3.5."; 1575 } 1577 leaf padding-length { 1578 type uint32 { 1579 range 64..4096; 1580 } 1581 description 1582 "The number of padding bytes to be added to the 1583 TWAMP-Test (UDP) packets generated by the 1584 Session-Sender. 1586 This value will be placed in the Padding Length 1587 field of the Request-TW-Session message."; 1588 reference 1589 "RFC 4656, Section 3.5."; 1590 } 1592 leaf test-packet-dscp { 1593 type inet:dscp; 1594 default 0; 1595 description 1596 "The DSCP value to be placed in the IP header 1597 of TWAMP-Test packets generated by the 1598 Session-Sender, and in the UDP header of the 1599 TWAMP-Test response packets generated by the 1600 Session-Reflector for this test session. 1602 This value will be placed in the Type-P Descriptor 1603 field of the Request-TW-Session message"; 1604 reference 1605 "RFC 5357."; 1606 } 1607 leaf start-time { 1608 type uint64; 1609 default 0; 1610 description 1611 "Time when the session is to be started 1612 (but not before the TWAMP Start-Sessions command 1613 is issued; see Section 3.4 of RFC 5357). 1615 The start-time value is placed in the Start Time 1616 field of the Request-TW-Session message. 1618 The timestamp format follows RFC 5905 as per 1619 Section 3.5 of RFC 4656. 1621 The default value of 0 indicates that the session 1622 will be started as soon as the Start-Sessions 1623 message is received."; 1624 } 1626 leaf repeat { 1627 type uint32 { 1628 range 0..4294967295; 1629 } 1630 default 0; 1631 description 1632 "This value determines if the TWAMP-Test session must 1633 be repeated. When a test session has completed, the 1634 repeat parameter is checked. 1636 The default value of 0 indicates that the session 1637 MUST NOT be repeated. 1639 If the repeat value is 1 through 4,294,967,294 1640 then the test session SHALL be repeated using the 1641 information in repeat-interval parameter, and the 1642 parent TWAMP-Control connection for this test 1643 session is restarted to negotiate a new instance 1644 of this TWAMP-Test session. 1646 A value of 4,294,967,295 indicates that the test 1647 session SHALL be repeated *forever* using the 1648 information in repeat-interval parameter, and SHALL 1649 NOT decrement the value."; 1650 } 1652 leaf repeat-interval { 1653 when "../repeat!='0'" { 1654 description 1655 "This parameter determines the timing of repeated 1656 TWAMP-Test sessions when repeat is more than 0. 1658 When the value of repeat-interval is 0, the 1659 negotiation of a new test session SHALL begin 1660 immediately after the previous test session 1661 completes. Otherwise, the Control-Client will 1662 wait for the number of seconds specified in the 1663 repeat-interval parameter before negotiating the 1664 new instance of this TWAMP-Test session."; 1665 } 1666 type uint32; 1667 units seconds; 1668 default 0; 1669 description 1670 "Repeat interval (in seconds)."; 1671 } 1673 list pm-reg-list { 1674 key pm-index; 1675 leaf pm-index { 1676 type uint16; 1677 description 1678 "Numerical index value of a Registered Metric 1679 in the Performance Metric Registry 1680 (see ietf-ippm-metric-registry). Output statistics 1681 are specified in the corresponding Registry 1682 entry."; 1683 } 1684 description 1685 "A list of one or more Performance Metric Registry 1686 Index values, which communicate packet stream 1687 characteristics along with one or more metrics 1688 to be measured. 1690 All members of the pm-reg-list MUST have the same 1691 stream characteristics, such that they combine 1692 to specify all metrics that shall be measured on 1693 a single stream."; 1694 reference 1695 "ietf-ippm-metric-registry: Registry for 1696 Performance Metrics"; 1697 } 1699 leaf state { 1700 type test-session-state; 1701 config false; 1702 description 1703 "Indicates the TWAMP-Test session state, accepted or 1704 indication of an error."; 1705 reference 1706 "Section 3.5 of RFC 5357."; 1707 } 1708 leaf sid { 1709 type string; 1710 config false; 1711 description 1712 "The SID allocated by the Server for this TWAMP-Test 1713 session, and communicated back to the Control-Client 1714 in the SID field of the Accept-Session message"; 1715 reference 1716 "Section 4.3 of RFC 6038."; 1717 } 1718 } 1719 } 1720 } 1722 container server { 1723 if-feature server; 1724 description 1725 "Configuration of the TWAMP Server logical entity."; 1727 leaf admin-state { 1728 type boolean; 1729 default true; 1730 description 1731 "Indicates whether the device is allowed to operate 1732 as a TWAMP Server."; 1733 } 1735 leaf server-tcp-port { 1736 type inet:port-number; 1737 default 862; 1738 description 1739 "This parameter defines the well known TCP port number 1740 that is used by TWAMP-Control. The Server will listen 1741 on this port number for incoming TWAMP-Control 1742 connections. Although this is defined as a fixed value 1743 (862) in RFC 5357, there are several realizations of 1744 TWAMP in the field that were implemented before this 1745 well-known port number was allocated. These early 1746 implementations allowed the port number to be 1747 configured. This parameter is therefore provided for 1748 backward compatibility reasons."; 1749 } 1750 leaf servwait { 1751 type uint32 { 1752 range 1..604800; 1753 } 1754 units seconds; 1755 default 900; 1756 description 1757 "TWAMP-Control (TCP) session timeout, in seconds. 1758 According to Section 3.1 of RFC 5357, 1760 Server MAY discontinue any established control 1761 connection when no packet associated with that 1762 connection has been received within SERVWAIT seconds."; 1763 } 1765 leaf control-packet-dscp { 1766 type inet:dscp; 1767 description 1768 "The DSCP value to be placed in the IP header of 1769 TWAMP-Control (TCP) packets generated by the Server. 1771 Section 3.1 of RFC 5357 specifies that the server 1772 SHOULD use the DSCP value from the Control-Clients 1773 TCP SYN. However, for practical purposes TWAMP will 1774 typically be implemented using a general purpose TCP 1775 stack provided by the underlying operating system, 1776 and such a stack may not provide this information to the 1777 user. Consequently, it is not always possible to 1778 implement the behavior described in RFC 5357 in an 1779 OS-portable version of TWAMP. 1781 The default behavior if this item is not set is to use 1782 the DSCP value from the Control-Clients TCP SYN."; 1783 reference 1784 "Section 3.1 of RFC 5357."; 1785 } 1787 uses count; 1789 uses max-count-exponent; 1791 leaf modes { 1792 type twamp-modes; 1793 description 1794 "The bit mask of TWAMP Modes this Server instance 1795 is willing to support; see IANA TWAMP Modes Registry."; 1796 } 1797 uses key-management; 1799 list ctrl-connection { 1800 key "client-ip client-tcp-port server-ip server-tcp-port"; 1801 config false; 1802 description 1803 "List of all incoming TWAMP-Control (TCP) connections."; 1805 leaf client-ip { 1806 type inet:ip-address; 1807 description 1808 "The IP address on the remote Control-Client device, 1809 which is the source IP address used in the 1810 TWAMP-Control (TCP) packets belonging to this control 1811 connection."; 1812 } 1814 leaf client-tcp-port { 1815 type inet:port-number; 1816 description 1817 "The source TCP port number used in the TWAMP-Control 1818 (TCP) packets belonging to this control connection."; 1819 } 1821 leaf server-ip { 1822 type inet:ip-address; 1823 description 1824 "The IP address of the local Server device, which is 1825 the destination IP address used in the 1826 TWAMP-Control (TCP) packets belonging to this control 1827 connection."; 1828 } 1830 leaf server-tcp-port { 1831 type inet:port-number; 1832 description 1833 "The destination TCP port number used in the 1834 TWAMP-Control (TCP) packets belonging to this 1835 control connection. This will usually be the 1836 same value as the server-tcp-port configured 1837 under twamp/server. However, in the event that 1838 the user re-configured server/server-tcp-port 1839 after this control connection was initiated, this 1840 value will indicate the server-tcp-port that is 1841 actually in use for this control connection."; 1842 } 1844 leaf state { 1845 type server-ctrl-connection-state; 1846 description 1847 "Indicates the Server TWAMP-Control connection state."; 1848 } 1850 leaf control-packet-dscp { 1851 type inet:dscp; 1852 description 1853 "The DSCP value used in the IP header of the 1854 TWAMP-Control (TCP) packets sent by the Server 1855 for this control connection. This will usually 1856 be the same value as is configured in the 1857 control-packet-dscp parameter under the twamp/server 1858 container. However, in the event that the user 1859 re-configures server/dscp after this control 1860 connection is already in progress, this read-only 1861 value will show the actual dscp value in use by this 1862 TWAMP-Control connection."; 1863 } 1865 leaf selected-mode { 1866 type twamp-modes; 1867 description 1868 "The Mode that was chosen for this TWAMP-Control 1869 connection as set in the Mode field of the 1870 Set-Up-Response message."; 1871 } 1873 leaf key-id { 1874 type string { 1875 length 1..80; 1876 } 1877 description 1878 "The KeyID value that is in use by this TWAMP-Control 1879 connection as selected by Control-Client."; 1880 } 1882 uses count { 1883 description 1884 "The count value that is in use by this TWAMP-Control 1885 connection. This will usually be the same value 1886 as is configured under twamp/server. However, in the 1887 event that the user re-configured server/count 1888 after this control connection is already in progress, 1889 this read-only value will show the actual count that 1890 is in use for this TWAMP-Control connection."; 1891 } 1892 uses max-count-exponent { 1893 description 1894 "This read-only value indicates the actual max-count in 1895 use for this control connection. Usually this would be 1896 the same value as configured under twamp/server."; 1897 } 1899 leaf salt { 1900 type binary { 1901 length 16; 1902 } 1903 description 1904 "A parameter used in deriving a key from a 1905 shared secret as described in Section 3.1 of RFC 4656. 1906 It is communicated to the Control-Client as part of 1907 the Server Greeting message."; 1908 } 1910 leaf server-iv { 1911 type binary { 1912 length 16; 1913 } 1914 description 1915 "The Server Initialization Vector 1916 (IV) generated randomly by the Server."; 1917 } 1919 leaf challenge { 1920 type binary { 1921 length 16; 1922 } 1923 description 1924 "A random sequence of octets generated by the Server. 1925 As described in client/token, Challenge is used 1926 by the Control-Client to prove possession of a 1927 shared secret."; 1928 } 1929 } 1930 } 1932 container session-sender { 1933 if-feature session-sender; 1934 description 1935 "Configuration of the TWAMP Session-Sender logical entity"; 1936 leaf admin-state { 1937 type boolean; 1938 default true; 1939 description 1940 "Indicates whether the device is allowed to operate 1941 as a TWAMP Session-Sender."; 1942 } 1944 list test-session{ 1945 key name; 1946 description 1947 "List of TWAMP Session-Sender test sessions."; 1949 leaf name { 1950 type string; 1951 description 1952 "A unique name for this TWAMP-Test session to be used 1953 for identifying this test session by the 1954 Session-Sender logical entity."; 1955 } 1957 leaf ctrl-connection-name { 1958 type string; 1959 config false; 1960 description 1961 "The name of the parent TWAMP-Control connection that 1962 is responsible for negotiating this TWAMP-Test 1963 session."; 1964 } 1966 leaf fill-mode { 1967 type padding-fill-mode; 1968 default zero; 1969 description 1970 "Indicates whether the padding added to the 1971 TWAMP-Test (UDP) packets will contain pseudo-random 1972 numbers, or whether it should consist of all zeroes, 1973 as per Section 4.2.1 of RFC 5357."; 1974 } 1976 leaf number-of-packets { 1977 type uint32; 1978 mandatory true; 1979 description 1980 "The overall number of TWAMP-Test (UDP) packets to be 1981 transmitted by the Session-Sender for this test 1982 session."; 1983 } 1985 choice packet-distribution { 1986 description 1987 "Indicates the distribution to be used for transmitting 1988 the TWAMP-Test (UDP) packets."; 1989 case periodic { 1990 leaf periodic-interval { 1991 type decimal64 { 1992 fraction-digits 5; 1993 } 1994 units seconds; 1995 mandatory true; 1996 description 1997 "Indicates the time to wait (in seconds) between 1998 the first bits of TWAMP-Test (UDP) packet 1999 transmissions for this test session."; 2000 reference 2001 "RFC 3432: Network performance measurement 2002 with periodic streams"; 2003 } 2004 } 2005 case poisson { 2006 leaf lambda { 2007 type decimal64 { 2008 fraction-digits 5; 2009 } 2010 units seconds; 2011 mandatory true; 2012 description 2013 "Indicates the average time interval (in seconds) 2014 between packets in the Poisson distribution. 2015 The packet is calculated using the reciprocal of 2016 lambda and the TWAMP-Test packet size (which 2017 depends on the selected Mode and the packet 2018 padding)."; 2019 reference 2020 "RFC 2330: Framework for IP Performance Metrics"; 2021 } 2022 leaf max-interval { 2023 type decimal64 { 2024 fraction-digits 5; 2025 } 2026 units seconds; 2027 description 2028 "Indicates the maximum time (in seconds) 2029 between packet transmissions."; 2030 reference 2031 "RFC 7312: Advanced Stream and Sampling Framework 2032 for IP Performance Metrics (IPPM)"; 2033 } 2034 } 2035 } 2036 leaf state { 2037 type sender-session-state; 2038 config false; 2039 description 2040 "Indicates the Session-Sender test session state."; 2041 } 2043 uses maintenance-statistics; 2044 } 2045 } 2047 container session-reflector { 2048 if-feature session-reflector; 2049 description 2050 "Configuration of the TWAMP Session-Reflector logical 2051 entity"; 2053 leaf admin-state { 2054 type boolean; 2055 default true; 2056 description 2057 "Indicates whether the device is allowed to operate 2058 as a TWAMP Session-Reflector."; 2059 } 2061 leaf refwait { 2062 type uint32 { 2063 range 1..604800; 2064 } 2065 units seconds; 2066 default 900; 2067 description 2068 "The Session-Reflector MAY discontinue any session that 2069 has been started when no packet associated with that 2070 session has been received for REFWAIT seconds. As per 2071 Section 3.1 of RFC 5357, this timeout allows a 2072 Session-Reflector to free up resources in case of 2073 failure."; 2074 } 2076 list test-session { 2077 key 2078 "sender-ip sender-udp-port 2079 reflector-ip reflector-udp-port"; 2080 config false; 2081 description 2082 "TWAMP Session-Reflectortest sessions."; 2084 leaf sid { 2085 type string; 2086 description 2087 "An auto-allocated identifier for this TWAMP-Test 2088 session that is unique within the context of this 2089 Server/Session-Reflector device only. This value 2090 is communicated to the Control-Client that 2091 requested the test session in the SID field of the 2092 Accept-Session message."; 2093 } 2095 leaf sender-ip { 2096 type inet:ip-address; 2097 description 2098 "The IP address on the remote device, which is the 2099 source IP address used in the TWAMP-Test (UDP) packets 2100 belonging to this test session."; 2101 } 2103 leaf sender-udp-port { 2104 type dynamic-port-number; 2105 description 2106 "The source UDP port used in the TWAMP-Test packets 2107 belonging to this test session."; 2108 } 2110 leaf reflector-ip { 2111 type inet:ip-address; 2112 description 2113 "The IP address of the local Session-Reflector 2114 device, which is the destination IP address used 2115 in the TWAMP-Test (UDP) packets belonging to this test 2116 session."; 2117 } 2119 leaf reflector-udp-port { 2120 type inet:port-number { 2121 range "862 | 49152..65535"; 2122 } 2123 description 2124 "The destination UDP port number used in the 2125 TWAMP-Test (UDP) test packets belonging to this 2126 test session."; 2127 } 2129 leaf parent-connection-client-ip { 2130 type inet:ip-address; 2131 description 2132 "The IP address on the Control-Client device, which 2133 is the source IP address used in the TWAMP-Control 2134 (TCP) packets belonging to the parent control 2135 connection that negotiated this test session."; 2136 } 2138 leaf parent-connection-client-tcp-port { 2139 type inet:port-number; 2140 description 2141 "The source TCP port number used in the TWAMP-Control 2142 (TCP) packets belonging to the parent control 2143 connection that negotiated this test session."; 2144 } 2146 leaf parent-connection-server-ip { 2147 type inet:ip-address; 2148 description 2149 "The IP address of the Server device, which is the 2150 destination IP address used in the TWAMP-Control 2151 (TCP) packets belonging to the parent control 2152 connection that negotiated this test session."; 2153 } 2155 leaf parent-connection-server-tcp-port { 2156 type inet:port-number; 2157 description 2158 "The destination TCP port number used in the 2159 TWAMP-Control (TCP) packets belonging to the parent 2160 control connection that negotiated this test 2161 session."; 2162 } 2164 leaf test-packet-dscp { 2165 type inet:dscp; 2166 description 2167 "The DSCP value present in the IP header of 2168 TWAMP-Test (UDP) packets belonging to this session."; 2169 } 2171 uses maintenance-statistics; 2172 } 2173 } 2174 } 2175 } 2177 2179 6. Data Model Examples 2181 This section presents a simple but complete example of configuring 2182 all four entities in Figure 1, based on the YANG module specified in 2183 Section 5. The example is illustrative in nature, but aims to be 2184 self-contained, i.e. were it to be executed in a real TWAMP 2185 implementation it would lead to a correctly configured test session. 2186 For completeness, examples are provided for both IPv4 and IPv6. 2188 A more elaborated example, which also includes authentication 2189 parameters, is provided in Appendix A. 2191 6.1. Control-Client 2193 Figure 8 shows a configuration example for a Control-Client with 2194 client/admin-state enabled. In a real implementation following 2195 Figure 2 this would permit the initiation of TWAMP-Control 2196 connections and TWAMP-Test sessions. 2198 2199 2200 2201 2202 true 2203 2204 2205 2207 Figure 8: XML instance enabling Control-Client operation. 2209 The following example shows a Control-Client with two instances of 2210 client/ctrl-connection, one called "RouterA" and another called 2211 "RouterB". Each TWAMP-Control connection is to a different Server. 2212 The control connection named "RouterA" has two test session requests. 2213 The TWAMP-Control connection named "RouterB" has no TWAMP-Test 2214 session requests. 2216 2217 2218 2219 2220 true 2221 2222 RouterA 2223 203.0.113.1 2224 203.0.113.2 2225 2226 Test1 2227 203.0.113.3 2228 54001 2229 203.0.113.4 2230 50001 2231 0 2232 2233 2234 Test2 2235 203.0.113.1 2236 54001 2237 203.0.113.2 2238 50001 2239 0 2240 2241 2242 2243 RouterB 2244 203.0.113.1 2245 203.0.113.3 2246 2247 2248 2249 2251 2252 2253 2254 2255 true 2256 2257 RouterA 2258 2001:DB8:203:0:113::1 2259 2001:DB8:203:0:113::2 2260 2261 Test1 2262 2001:DB8:203:1:113::3 2263 54000 2264 2001:DB8:203:1:113::4 2265 55000 2266 0 2267 2268 2269 Test2 2270 2001:DB8:203:0:113::1 2271 54001 2272 2001:DB8:203:0:113::2 2273 55001 2274 0 2275 2276 2277 2278 RouterB 2279 2001:DB8:203:0:113::1 2280 2001:DB8:203:0:113::3 2281 2282 2283 2284 2286 6.2. Server 2288 Figure 9 shows a configuration example for a Server with server/ 2289 admin-state enabled, which permits a device following Figure 2 to 2290 respond to TWAMP-Control connections and TWAMP-Test sessions. 2292 2293 2294 2295 2296 true 2297 2298 2299 2301 Figure 9: XML instance enabling Server operation. 2303 The following example presents a Server with the TWAMP-Control 2304 connection corresponding to the control connection name (client/ctrl- 2305 connection/name) "RouterA" presented in Section 6.1. 2307 2308 2309 2310 2311 true 2312 2313 203.0.113.1 2314 16341 2315 203.0.113.2 2316 862 2317 active 2318 2319 2320 2321 2323 2324 2325 2326 2327 true 2328 2329 2001:DB8:203:0:113::1 2330 16341 2331 2001:DB8:203:0:113::2 2332 862 2333 active 2334 2335 2336 2337 2339 6.3. Session-Sender 2341 Figure 10 shows a configuration example for a Session-Sender with 2342 session-sender/admin-state enabled, which permits a device following 2343 Figure 2 to initiate TWAMP-Test sessions. 2345 2346 2347 2348 2349 true 2350 2351 2352 2354 Figure 10: XML instance enabling Session-Sender operation. 2356 The following configuration example shows a Session-Sender with the 2357 two TWAMP-Test sessions presented in Section 6.1. 2359 2360 2361 2362 2363 true 2364 2365 Test1 2366 RouterA 2367 900 2368 1 2369 2370 2371 Test2 2372 RouterA 2373 900 2374 1 2375 2 2376 2377 2378 2379 2381 6.4. Session-Reflector 2383 This configuration example shows a Session-Reflector with session- 2384 reflector/admin-state enabled, which permits a device following 2385 Figure 2 to respond to TWAMP-Test sessions. 2387 2388 2389 2390 2391 true 2392 2393 2394 2396 Figure 11: XML instance enabling Session-Reflector operation. 2398 The following example shows the two Session-Reflector TWAMP-Test 2399 sessions corresponding to the test sessions presented in Section 6.3. 2401 [note: '\' line wrapping is for formatting only] 2403 2404 2405 2406 2407 true 2408 2409 203.0.113.3 2410 54000 2411 203.0.113.4 2412 50001 2413 1232 2414 203.0.113.1 2416 16341 2418 203.0.113.2 2420 862 2422 2 2423 2 2424 1 2425 1 2426 2427 2428 203.0.113.1 2429 54001 2430 192.0.2.2 2431 50001 2432 178943 2433 203.0.113.1 2436 16341 2438 203.0.113.2 2440 862 2442 21 2443 21 2444 20 2445 20 2446 2447 2448 2449 2451 [note: '\' line wrapping is for formatting only] 2453 2454 2455 2456 2457 true 2458 2459 203.0.113.3 2460 54000 2461 203.0.113.4 2462 54001 2463 1232 2464 203.0.113.1 2466 16341 2468 203.0.113.2 2470 862 2472 2 2473 2 2474 1 2475 1 2476 2477 2478 203.0.113.1 2479 54001 2480 192.0.2.2 2481 55001 2482 178943 2483 203.0.113.1 2485 16341 2487 203.0.113.2 2489 862 2491 21 2492 21 2493 20 2494 20 2495 2496 2497 2498 2500 7. Security Considerations 2502 Virtually all existing measurement systems using TWAMP [RFC5357] are 2503 administered by the same network operator. Attacks on the 2504 measurement infrastructure could be launched by third-parties to 2505 commandeer the packet generation capability, corrupt the 2506 measurements, or other examples of nefarious acts. 2508 The YANG module specified in Section 5 of this document defines a 2509 schema for data that is designed to be accessed via network 2510 management protocols such as NETCONF [RFC6241] or RESTCONF [RFC8040]. 2511 The lowest NETCONF [RFC6241] layer is the secure transport layer, and 2512 the mandatory-to-implement secure transport is Secure Shell (SSH) 2513 [RFC6242]. The lowest RESTCONF layer is HTTPS, and the mandatory-to- 2514 implement secure transport is TLS [RFC5246]. 2516 The NETCONF Access Control Module (NACM) [RFC8341] provides the means 2517 to restrict access for particular NETCONF or RESTCONF users to a 2518 preconfigured subset of all available NETCONF or RESTCONF protocol 2519 operations and content. 2521 There are a number of nodes defined in this YANG module which are 2522 writeable. These data nodes may be considered sensitive and 2523 vulnerable to attacks in some network environments. Ability to write 2524 into these nodes without proper protection can have a negative effect 2525 on the devices that support this feature. 2527 If written, the 'admin-state' node can cause unintended test sessions 2528 to be created. If the node 'number-of-packets' that dictates how 2529 many packets are sent in any particular test session is written with 2530 a large value, it can cause a test session to run longer than 2531 expected. Nodes that are particularly vulnerable include several 2532 timeout values put in the protocol to protect against sessions that 2533 are not active but are consuming resources. These are the REFWAIT 2534 timeout parameter which determine whether to discontinue the session 2535 if no packets are received, and nodes 'count' and 'max-count- 2536 exponent' which can cause a long time to be spent on PBKDF2 2537 iterations. In addition, 'dscp' node marked with different DSCP 2538 markings, can cause the test traffic on the network to be skewed, and 2539 the result manipulated. Finally, nodes within 'mode-preference- 2540 chain' which specify the 'mode' and 'priority' values and indicate 2541 the preferred order of use by an operator, can be manipulated to send 2542 unauthenticated or non-encrypted traffic, enabling a MITM attack. 2543 Limiting access to these nodes will limit the ability to launch an 2544 attack in network environments. 2546 The 'token' node defined in the model, containing a concatenation of 2547 a Challenge, AES Session-key used for encryption, and HMAC-SHA1 2548 Session-key used for authentication, is sensitive from a privacy 2549 perspective, and can be used to disrupt a test session. The ability 2550 to read the field should be limited to the administrator of the test 2551 network. 2553 8. IANA Considerations 2555 This document registers a URI in the IETF XML registry [RFC3688]. 2556 Following the format in IETF XML Registry [RFC3688], the following 2557 registration is requested to be made. 2559 URI: urn:ietf:params:xml:ns:yang:ietf-twamp 2561 Registrant Contact: The IESG. 2563 XML: N/A, the requested URI is an XML namespace. 2565 This document registers a YANG module in the YANG Module Names 2566 registry YANG [RFC6020]. 2568 name: ietf-twamp 2570 namespace: urn:ietf:params:xml:ns:yang:ietf-twamp 2572 prefix: twamp 2574 reference: RFC XXXX 2576 9. Acknowledgements 2578 We thank Fred Baker, Kevin D'Souza, Gregory Mirsky, Brian Trammell, 2579 Robert Sherman, and Marius Georgescu for their thorough and 2580 constructive reviews, comments and text suggestions. 2582 Haoxing Shen contributed to the definition of the YANG module in 2583 Section 5. 2585 Jan Lindblad and Ladislav Lhokta did thorough reviews of the YANG 2586 module and the examples in Appendix A. 2588 Kostas Pentikousis was partially supported by FP7 UNIFY 2589 (http://fp7-unify.eu), a research project partially funded by the 2590 European Community under the Seventh Framework Program (grant 2591 agreement no. 619609). The views expressed here are those of the 2592 authors only. The European Commission is not liable for any use that 2593 may be made of the information in this document. 2595 10. Contributors 2597 Lianshu Zheng. 2599 11. References 2601 11.1. Normative References 2603 [I-D.ietf-ippm-metric-registry] 2604 Bagnulo, M., Claise, B., Eardley, P., Morton, A., and A. 2605 Akhter, "Registry for Performance Metrics", draft-ietf- 2606 ippm-metric-registry-14 (work in progress), March 2018. 2608 [I-D.ietf-ippm-port-twamp-test] 2609 Morton, A. and G. Mirsky, "OWAMP and TWAMP Well-Known Port 2610 Assignments", draft-ietf-ippm-port-twamp-test-01 (work in 2611 progress), March 2018. 2613 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2614 Requirement Levels", BCP 14, RFC 2119, 2615 DOI 10.17487/RFC2119, March 1997, 2616 . 2618 [RFC3432] Raisanen, V., Grotefeld, G., and A. Morton, "Network 2619 performance measurement with periodic streams", RFC 3432, 2620 DOI 10.17487/RFC3432, November 2002, 2621 . 2623 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2624 DOI 10.17487/RFC3688, January 2004, 2625 . 2627 [RFC4086] Eastlake 3rd, D., Schiller, J., and S. Crocker, 2628 "Randomness Requirements for Security", BCP 106, RFC 4086, 2629 DOI 10.17487/RFC4086, June 2005, 2630 . 2632 [RFC4656] Shalunov, S., Teitelbaum, B., Karp, A., Boote, J., and M. 2633 Zekauskas, "A One-way Active Measurement Protocol 2634 (OWAMP)", RFC 4656, DOI 10.17487/RFC4656, September 2006, 2635 . 2637 [RFC5357] Hedayat, K., Krzanowski, R., Morton, A., Yum, K., and J. 2638 Babiarz, "A Two-Way Active Measurement Protocol (TWAMP)", 2639 RFC 5357, DOI 10.17487/RFC5357, October 2008, 2640 . 2642 [RFC5905] Mills, D., Martin, J., Ed., Burbank, J., and W. Kasch, 2643 "Network Time Protocol Version 4: Protocol and Algorithms 2644 Specification", RFC 5905, DOI 10.17487/RFC5905, June 2010, 2645 . 2647 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2648 the Network Configuration Protocol (NETCONF)", RFC 6020, 2649 DOI 10.17487/RFC6020, October 2010, 2650 . 2652 [RFC6038] Morton, A. and L. Ciavattone, "Two-Way Active Measurement 2653 Protocol (TWAMP) Reflect Octets and Symmetrical Size 2654 Features", RFC 6038, DOI 10.17487/RFC6038, October 2010, 2655 . 2657 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 2658 RFC 6991, DOI 10.17487/RFC6991, July 2013, 2659 . 2661 [RFC7717] Pentikousis, K., Ed., Zhang, E., and Y. Cui, 2662 "IKEv2-Derived Shared Secret Key for the One-Way Active 2663 Measurement Protocol (OWAMP) and Two-Way Active 2664 Measurement Protocol (TWAMP)", RFC 7717, 2665 DOI 10.17487/RFC7717, December 2015, 2666 . 2668 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2669 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2670 . 2672 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2673 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2674 May 2017, . 2676 [UML] ISO/IEC, "Information technology - Open Distributed 2677 Processing - Unified Modeling Language", April 2005. 2679 11.2. Informative References 2681 [NSC] John, W., Pentikousis, K., et al., "Research directions in 2682 network service chaining", Proc. SDN for Future Networks 2683 and Services (SDN4FNS), Trento, Italy IEEE, November 2013. 2685 [RFC2330] Paxson, V., Almes, G., Mahdavi, J., and M. Mathis, 2686 "Framework for IP Performance Metrics", RFC 2330, 2687 DOI 10.17487/RFC2330, May 1998, 2688 . 2690 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2691 (TLS) Protocol Version 1.2", RFC 5246, 2692 DOI 10.17487/RFC5246, August 2008, 2693 . 2695 [RFC5618] Morton, A. and K. Hedayat, "Mixed Security Mode for the 2696 Two-Way Active Measurement Protocol (TWAMP)", RFC 5618, 2697 DOI 10.17487/RFC5618, August 2009, 2698 . 2700 [RFC5938] Morton, A. and M. Chiba, "Individual Session Control 2701 Feature for the Two-Way Active Measurement Protocol 2702 (TWAMP)", RFC 5938, DOI 10.17487/RFC5938, August 2010, 2703 . 2705 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2706 and A. Bierman, Ed., "Network Configuration Protocol 2707 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2708 . 2710 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 2711 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 2712 . 2714 [RFC7312] Fabini, J. and A. Morton, "Advanced Stream and Sampling 2715 Framework for IP Performance Metrics (IPPM)", RFC 7312, 2716 DOI 10.17487/RFC7312, August 2014, 2717 . 2719 [RFC7426] Haleplidis, E., Ed., Pentikousis, K., Ed., Denazis, S., 2720 Hadi Salim, J., Meyer, D., and O. Koufopavlou, "Software- 2721 Defined Networking (SDN): Layers and Architecture 2722 Terminology", RFC 7426, DOI 10.17487/RFC7426, January 2723 2015, . 2725 [RFC8018] Moriarty, K., Ed., Kaliski, B., and A. Rusch, "PKCS #5: 2726 Password-Based Cryptography Specification Version 2.1", 2727 RFC 8018, DOI 10.17487/RFC8018, January 2017, 2728 . 2730 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2731 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2732 . 2734 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 2735 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 2736 . 2738 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 2739 Access Control Model", STD 91, RFC 8341, 2740 DOI 10.17487/RFC8341, March 2018, 2741 . 2743 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 2744 and R. Wilton, "Network Management Datastore Architecture 2745 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 2746 . 2748 Appendix A. Detailed Data Model Examples 2750 This appendix extends the example presented in Section 6 by 2751 configuring more fields such as authentication parameters, DSCP 2752 values and so on. 2754 A.1. Control-Client 2756 2757 2758 2759 2760 true 2761 2762 0 2763 authenticated 2764 2765 2766 1 2767 unauthenticated 2768 2769 2770 KeyClient1ToRouterA 2771 c2VjcmV0MQ== 2772 2773 2774 KeyForRouterB 2775 c2VjcmV0Mg0K 2776 2777 2778 RouterA 2779 203.0.113.1 2780 203.0.113.2 2781 32 2782 KeyClient1ToRouterA 2783 2784 Test1 2785 203.0.113.3 2786 54000 2787 203.0.113.4 2788 55000 2789 64 2790 0 2791 2792 2793 Test2 2794 203.0.113.1 2795 54001 2796 203.0.113.2 2797 55001 2798 128 2799 0 2800 2801 2802 2803 2804 2806 2807 2808 2809 2810 true 2811 2812 0 2813 authenticated 2814 2815 2816 1 2817 unauthenticated 2818 2819 2820 KeyClient1ToRouterA 2821 c2VjcmV0MQ== 2822 2823 2824 KeyForRouterB 2825 c2VjcmV0Mg0K 2826 2827 2828 RouterA 2829 2001:DB8:203:0:113::1 2830 2001:DB8:203:0:113::2 2831 32 2832 KeyClient1ToRouterA 2833 2834 Test1 2835 2001:DB8:10:1:1::1 2836 54000 2837 2001:DB8:10:1:1::2 2838 55000 2839 64 2840 0 2841 2842 2843 Test2 2844 2001:DB8:203:0:113::1 2845 54001 2846 2001:DB8:203:0:113::2 2847 55001 2848 128 2849 0 2850 2851 2852 2853 2854 2856 A.2. Server 2858 2859 2860 2861 2862 true 2863 1800 2864 32 2865 authenticated unauthenticated 2866 15 2867 2868 KeyClient1ToRouterA 2869 c2VjcmV0MQ== 2870 2871 2872 KeyClient10ToRouterA 2873 c2VjcmV0MTANCg== 2874 2875 2876 203.0.113.1 2877 16341 2878 203.0.113.2 2879 862 2880 32 2881 unauthenticated 2882 KeyClient1ToRouterA 2883 15 2884 2885 2886 2887 2889 2890 2891 2892 2893 true 2894 1800 2895 32 2896 authenticated unauthenticated 2897 15 2898 2899 KeyClient1ToRouterA 2900 c2VjcmV0MQ== 2901 2902 2903 KeyClient10ToRouterA 2904 c2VjcmV0MTANCg== 2905 2906 2907 2001:DB8:203:0:113::1 2908 16341 2909 2001:DB8:203:0:113::2 2910 862 2911 32 2912 unauthenticated 2913 KeyClient1ToRouterA 2914 15 2915 2916 2917 2918 2920 A.3. Session-Sender 2922 2923 2924 2925 2926 true 2927 2928 Test1 2929 RouterA 2930 zero 2931 900 2932 1 2933 2 2934 2 2935 1 2936 1 2937 2938 2939 Test2 2940 RouterA 2941 random 2942 900 2943 1 2944 2 2945 21 2946 21 2947 20 2948 20 2949 2950 2951 2952 2954 A.4. Session-Reflector 2956 [note: '\' line wrapping is for formatting only] 2958 2959 2960 2961 2962 true 2963 2964 203.0.113.3 2965 54000 2966 203.0.113.4 2967 55000 2968 1232 2969 203.0.113.1 2971 16341 2973 203.0.113.2 2975 862 2977 32 2978 2 2979 2 2980 1 2981 1 2982 2983 2984 203.0.113.1 2985 54001 2986 192.0.2.2 2987 55001 2988 178943 2989 203.0.113.1 2991 16341 2993 203.0.113.2 2995 862 2997 32 2998 21 2999 21 3000 20 3001 20 3003 3004 3005 3006 3008 [note: '\' line wrapping is for formatting only] 3010 3011 3012 3013 3014 true 3015 3016 2001:DB8:10:1:1::1 3017 54000 3018 2001:DB8:10:1:1::2 3019 55000 3020 1232 3021 2001:DB8:203:0:113::1 3023 16341 3025 2001:DB8:203:0:113::2 3027 862 3029 32 3030 2 3031 2 3032 1 3033 1 3034 3035 3036 2001:DB8:203:0:113::1 3037 54001 3038 2001:DB8:192:68::2 3039 55001 3040 178943 3041 2001:DB8:203:0:113::1 3043 16341 3045 2001:DB8:203:0:113::2 3047 862 3049 32 3050 21 3051 21 3052 20 3053 20 3054 3055 3056 3057 3059 Appendix B. TWAMP Operational Commands 3061 TWAMP operational commands could be performed programmatically or 3062 manually, e.g. using a command-line interface (CLI). 3064 With respect to programmability, YANG can be used to define NETCONF 3065 Remote Procedure Calls (RPC), therefore it would be, in principle, 3066 possible to define TWAMP RPC operations for actions such as starting 3067 or stopping control connections or test sessions or groups of 3068 sessions; retrieving results; clearing stored results, and so on. 3070 However, TWAMP [RFC5357] does not attempt to describe such 3071 operational actions. Refer also to Section 2 and the unlabeled links 3072 in Figure 1. In actual deployments different TWAMP implementations 3073 may support different sets of operational commands, with different 3074 restrictions. Therefore, this document considers it the 3075 responsibility of the individual implementation to define its 3076 corresponding TWAMP operational commands data model. 3078 Authors' Addresses 3080 Ruth Civil 3081 Ciena Corporation 3082 307 Legget Drive 3083 Kanata, ON K2K 3C8 3084 Canada 3086 Email: gcivil@ciena.com 3087 URI: www.ciena.com 3088 Al Morton 3089 AT&T Labs 3090 200 Laurel Avenue South 3091 Middletown,, NJ 07748 3092 USA 3094 Phone: +1 732 420 1571 3095 Fax: +1 732 368 1192 3096 Email: acmorton@att.com 3098 Reshad Rahman 3099 Cisco Systems 3100 2000 Innovation Drive 3101 Kanata, ON K2K 3E8 3102 Canada 3104 Email: rrahman@cisco.com 3106 Mahesh Jethanandani 3107 Xoriant Corporation 3108 1248 Reamswood Drive 3109 Sunnyvale, CA 94089 3110 USA 3112 Email: mjethanandani@gmail.com 3114 Kostas Pentikousis (editor) 3115 Travelping 3116 Siemensdamm 50 3117 Berlin 13629 3118 Germany 3120 Email: k.pentikousis@travelping.com