idnits 2.17.1 draft-ietf-ippm-twamp-yang-08.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 675 has weird spacing: '...riority uin...' == Line 709 has weird spacing: '...m-index uin...' -- The document date (April 14, 2018) is 2202 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'I-D.unify-nfvrg-challenges' is defined on line 2665, but no explicit reference was found in the text == Outdated reference: A later version (-04) exists of draft-ietf-ippm-port-twamp-test-01 ** Obsolete normative reference: RFC 1305 (Obsoleted by RFC 5905) ** Downref: Normative reference to an Informational RFC: RFC 7312 == Outdated reference: A later version (-24) exists of draft-ietf-ippm-metric-registry-14 -- Obsolete informational reference (is this intentional?): RFC 5246 (Obsoleted by RFC 8446) Summary: 2 errors (**), 0 flaws (~~), 6 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: October 16, 2018 AT&T Labs 6 R. Rahman 7 Cisco Systems 8 M. Jethanandani 10 K. Pentikousis, Ed. 11 Travelping 12 April 14, 2018 14 Two-Way Active Measurement Protocol (TWAMP) Data Model 15 draft-ietf-ippm-twamp-yang-08 17 Abstract 19 This document specifies a data model for client and server 20 implementations of the Two-Way Active Measurement Protocol (TWAMP). 21 We define the TWAMP data model through Unified Modeling Language 22 (UML) class diagrams and formally specify it using YANG. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at https://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on October 16, 2018. 41 Copyright Notice 43 Copyright (c) 2018 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (https://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 59 1.1. Motivation . . . . . . . . . . . . . . . . . . . . . . . 3 60 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 61 1.3. Document Organization . . . . . . . . . . . . . . . . . . 4 62 2. Scope, Model, and Applicability . . . . . . . . . . . . . . . 4 63 3. Data Model Overview . . . . . . . . . . . . . . . . . . . . . 5 64 3.1. Control-Client . . . . . . . . . . . . . . . . . . . . . 6 65 3.2. Server . . . . . . . . . . . . . . . . . . . . . . . . . 7 66 3.3. Session-Sender . . . . . . . . . . . . . . . . . . . . . 7 67 3.4. Session-Reflector . . . . . . . . . . . . . . . . . . . . 8 68 4. Data Model Parameters . . . . . . . . . . . . . . . . . . . . 8 69 4.1. Control-Client . . . . . . . . . . . . . . . . . . . . . 8 70 4.2. Server . . . . . . . . . . . . . . . . . . . . . . . . . 11 71 4.3. Session-Sender . . . . . . . . . . . . . . . . . . . . . 13 72 4.4. Session-Reflector . . . . . . . . . . . . . . . . . . . . 14 73 5. Data Model . . . . . . . . . . . . . . . . . . . . . . . . . 16 74 5.1. YANG Tree Diagram . . . . . . . . . . . . . . . . . . . . 16 75 5.2. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 19 76 6. Data Model Examples . . . . . . . . . . . . . . . . . . . . . 48 77 6.1. Control-Client . . . . . . . . . . . . . . . . . . . . . 48 78 6.2. Server . . . . . . . . . . . . . . . . . . . . . . . . . 50 79 6.3. Session-Sender . . . . . . . . . . . . . . . . . . . . . 51 80 6.4. Session-Reflector . . . . . . . . . . . . . . . . . . . . 52 81 7. Security Considerations . . . . . . . . . . . . . . . . . . . 55 82 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 56 83 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 56 84 10. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 56 85 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 57 86 11.1. Normative References . . . . . . . . . . . . . . . . . . 57 87 11.2. Informative References . . . . . . . . . . . . . . . . . 58 88 Appendix A. Detailed Data Model Examples . . . . . . . . . . . . 60 89 A.1. Control-Client . . . . . . . . . . . . . . . . . . . . . 60 90 A.2. Server . . . . . . . . . . . . . . . . . . . . . . . . . 62 91 A.3. Session-Sender . . . . . . . . . . . . . . . . . . . . . 63 92 A.4. Session-Reflector . . . . . . . . . . . . . . . . . . . . 64 93 Appendix B. TWAMP Operational Commands . . . . . . . . . . . . . 67 94 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 67 96 1. Introduction 98 The Two-Way Active Measurement Protocol (TWAMP) [RFC5357] is used to 99 measure network performance parameters such as latency, bandwidth, 100 and packet loss by sending probe packets and measuring their 101 experience in the network. To date, TWAMP implementations do not 102 come with a standard management framework, and, as such, implementors 103 have no choice except to provide a proprietary mechanism. This 104 document addresses this gap by formally specifying the TWAMP data 105 model using YANG [RFC7950]. 107 1.1. Motivation 109 In current TWAMP deployments the lack of a standardized data model 110 limits the flexibility to dynamically instantiate TWAMP-based 111 measurements across equipment from different vendors. In large, 112 virtualized, and dynamically instantiated infrastructures where 113 network functions are placed according to orchestration algorithms as 114 discussed in Unifying Carrier and Cloud Networks: Problem Statement 115 and Challenges [I-D.unify-nfvrg-challenges]DevOps For Software- 116 Defined Telecom Infrastructures [I-D.unify-nfvrg-devops], proprietary 117 mechanisms for managing TWAMP measurements pose severe limitations 118 with respect to programmability. 120 Two major trends call for standardizing TWAMP management aspects. 121 First, we expect that in the coming years large-scale and multi- 122 vendor TWAMP deployments will become the norm. From an operations 123 perspective, using several vendor-specific TWAMP configuration 124 mechanisms when one standard mechanism could provide an alternative 125 is expensive and inefficient. Second, the increasingly software- 126 defined and virtualized nature of network infrastructures, based on 127 dynamic service chains [NSC] and programmable control and management 128 planes Software-Defined Networking (SDN): Layers and Architecture 129 Terminology [RFC7426] requires a well-defined data model for TWAMP 130 implementations. This document defines such a TWAMP data model and 131 specifies it formally using the YANG [RFC7950] data modeling 132 language. 134 Note to RFC Editor: 136 Please replace the date 2018-04-16 in Section 5.2 of the draft with 137 the date of publication of this draft as a RFC. Also, replace 138 reference to RFC XXXX, and draft-ietf-port-twamp-test with the RFC 139 numbers assigned to the drafts. 141 1.2. Terminology 143 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 144 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 145 "OPTIONAL" in this document are to be interpreted as described in BCP 146 14 [RFC2119] [RFC8174] when, and only when, they appear in all 147 capitals, as shown here. 149 1.3. Document Organization 151 The rest of this document is organized as follows. Section 2 152 presents the scope and applicability of this document. Section 3 153 provides a high-level overview of the TWAMP data model. Section 4 154 details the configuration parameters of the data model and Section 5 155 specifies in YANG the TWAMP data model. Section 6 lists illustrative 156 examples which conform to the YANG data model specified in this 157 document. Appendix A elaborates these examples further. 159 2. Scope, Model, and Applicability 161 The purpose of this document is the specification of a vendor- 162 independent data model for TWAMP implementations. 164 Figure 1 illustrates a redrawn version of the TWAMP logical model 165 found in Section 1.2 of TWAMP [RFC5357]. The figure is annotated 166 with pointers to the UML diagrams provided in this document and 167 associated with the data model of the four logical entities in a 168 TWAMP deployment, namely the TWAMP Control-Client, Server, Session- 169 Sender and Session-Reflector. 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. 225 3. Data Model Overview 227 The TWAMP data model includes four categories of configuration items. 229 First, global configuration items relate to parameters that are set 230 on a per device level. For example, the administrative status of the 231 device with respect to whether it allows TWAMP sessions and, if so, 232 in what capacity (e.g. Control-Client, Server or both), is a typical 233 instance of a global configuration item. 235 A second category includes attributes that can be configured on a per 236 TWAMP-Control connection basis, such as the Server IP address. 238 A third category includes attributes related to per TWAMP-Test 239 session attributes, for instance setting different values in the 240 Differentiated Services Code Point (DSCP) field. 242 Finally, the data model includes attributes that relate to the 243 operational state of the TWAMP implementation. 245 As we describe the TWAMP data model in the remaining sections of this 246 document, readers should keep in mind the functional entity grouping 247 illustrated in Figure 1. 249 3.1. Control-Client 251 A TWAMP Control-Client has an administrative status field set at the 252 device level that indicates whether the node is enabled to function 253 as such. 255 Each TWAMP Control-Client is associated with zero or more TWAMP- 256 Control connections. The main configuration parameters of each 257 control connection are: 259 o A name which can be used to uniquely identify at the Control- 260 Client a particular control connection. This name is necessary 261 for programmability reasons because at the time of creation of a 262 TWAMP-Control connection not all IP and TCP port number 263 information needed to uniquely identify the connection is 264 available. 266 o The IP address of the interface the Control-Client will use for 267 connections. 269 o The IP address of the remote TWAMP Server. 271 o Authentication and encryption attributes such as KeyID, Token and 272 the Client Initialization Vector (Client-IV); see also the last 273 paragraph of Section 6 in OWAMP [RFC4656] and Randomness 274 Requirements for Security [RFC4086]. 276 Each TWAMP-Control connection, in turn, is associated with zero or 277 more TWAMP-Test sessions. For each test session we note the 278 following configuration items: 280 o The test session name that uniquely identifies a particular test 281 session at the Control-Client and Session-Sender. Similarly to 282 the control connections above, this unique test session name is 283 needed because at the time of creation of a TWAMP-Test session, 284 for example, the source UDP port number is not known to uniquely 285 identify the test session. 287 o The IP address and UDP port number of the Session-Sender on the 288 path under test by TWAMP. 290 o The IP address and UDP port number of the Session-Reflector on 291 said path. 293 o Information pertaining to the test packet stream, such as the test 294 starting time, which performance metric is to be used Registry for 295 Performance Metrics [I-D.ietf-ippm-metric-registry], or whether 296 the test should be repeated. 298 3.2. Server 300 Each TWAMP Server has an administrative status field set at the 301 device level to indicate whether the node is enabled to function as a 302 TWAMP Server. 304 Each Server is associated with zero or more TWAMP-Control 305 connections. Each control connection is uniquely identified by the 306 4-tuple {Control-Client IP address, Control-Client TCP port number, 307 Server IP address, Server TCP port}. Control connection configuration 308 items on a TWAMP Server are read-only. 310 3.3. Session-Sender 312 A TWAMP Session-Sender has an administrative status field set at the 313 device level that indicates whether the node is enabled to function 314 as such. 316 There is one Session-Sender instance for each TWAMP-Test session that 317 is initiated from the sending device. Primary configuration fields 318 include: 320 o The test session name that MUST be identical with the 321 corresponding test session name on the TWAMP Control-Client 322 (Section 3.1). 324 o The control connection name, which along with the test session 325 name uniquely identify the TWAMP Session-Sender instance. 327 o Information pertaining to the test packet stream, such as, for 328 example, the number of test packets and the packet distribution to 329 be employed; see also Network performence measurement with 330 periodic streams [RFC3432]. 332 3.4. Session-Reflector 334 Each TWAMP Session-Reflector has an administrative status field set 335 at the device level to indicate whether the node is enabled to 336 function as such. 338 Each Session-Reflector is associated with zero or more TWAMP-Test 339 sessions. For each test session, the REFWAIT timeout parameter which 340 determines whether to discontinue the session if no packets have been 341 received (TWAMP [RFC5357], Section 4.2) can be configured. 343 Read-only access to other data model parameters, such as the Sender 344 IP address is foreseen. Each test session can be uniquely identified 345 by the 4-tuple mentioned in Section 3.2. 347 4. Data Model Parameters 349 This section defines the TWAMP data model using UML and introduces 350 selected parameters associated with the four TWAMP logical entities. 351 The complete TWAMP data model specification is provided in the YANG 352 module presented in Section 5.2. 354 4.1. Control-Client 356 The client container (see Figure 3) holds items that are related to 357 the configuration of the TWAMP Control-Client logical entity (recall 358 Figure 1). 360 The client container includes an administrative configuration 361 parameter (client/admin-state) that indicates whether the device is 362 allowed to initiate TWAMP-Control connections. 364 +-------------+ 365 | client | 366 +-------------+ 1..* +-----------------------+ 367 | admin-state |<>----------------------| mode-preference-chain | 368 | | +-----------------------+ 369 | | 1..* +------------+ | priority | 370 | |<>-----| key-chain | | mode | 371 +-------------+ +------------+ +-----------------------+ 372 ^ | key-id | 373 V | secret-key | 374 | +------------+ 375 | 0..* 376 +------------------------+ 377 | ctrl-connection | 378 +------------------------+ 379 | name | 380 | client-ip | 381 | server-ip | 382 | server-tcp-port | 0..* +----------------------+ 383 | control-packet-dscp |<>-------| test-session-request | 384 | key-id | +----------------------+ 385 | max-count | | name | 386 | client-tcp-port {ro} | | sender-ip | 387 | server-start-time {ro} | | sender-udp-port | 388 | state {ro} | | reflector-ip | 389 | selected-mode {ro} | | reflector-udp-port | 390 | token {ro} | | timeout | 391 | client-iv {ro} | | padding-length | 392 +------------------------+ | test-packet-dscp | 393 | start-time | 394 +-------------+ 1 | repeat | 395 | pm-reg-list |------<>| repeat-interval | 396 +-------------+ | state {ro} | 397 | pm-index | | sid {ro} | 398 +-------------+ +----------------------+ 400 Figure 3: TWAMP Control-Client UML class diagram 402 The client container holds a list (mode-preference-chain) which 403 specifies the Mode values according to their preferred order of use 404 by the operator of this Control-Client, including the authentication 405 and encryption Modes. Specifically, mode-preference-chain lists the 406 mode and its corresponding priority, expressed as a 16-bit unsigned 407 integer, where zero is the highest priority and subsequent values are 408 monotonically increasing. 410 Depending on the Modes available in the Server Greeting, the Control- 411 Client MUST choose the highest priority Mode from the configured 412 mode-preference-chain list. 414 Note that the list of preferred Modes may set bit position 415 combinations when necessary, such as when referring to the extended 416 TWAMP features in Mixed Security Mode for TWAMP [RFC5618], Individual 417 Session Control Feature for TWAMP [RFC5938], TWAMP Reflect Octets and 418 Symmetrical Size Features [RFC6038], and IKEv2-Derived Shared Secret 419 Key for OWAMP and TWAMP [RFC7717]. If the Control-Client cannot 420 determine an acceptable Mode, it MUST respond with zero Mode bits set 421 in the Set-up Response message, indicating it will not continue with 422 the control connection. 424 In addition, the client container holds a list named key-chain which 425 relates KeyIDs with the respective secret keys. Both the Server and 426 the Control-Client use the same mappings from KeyIDs to shared 427 secrets (key-id and secret-key in Figure 3, respectively). The 428 Server, being prepared to conduct sessions with more than one 429 Control-Client, uses KeyIDs to choose the appropriate secret-key; a 430 Control-Client would typically have different secret keys for 431 different Servers. The secret-key is the shared secret, an octet 432 string of arbitrary length whose interpretation as a text string is 433 unspecified. The key-id and secret-key encoding SHOULD follow 434 Section 9.4 of YANG [RFC7950]. The derived key length (dkLen in PKCS 435 #5: Password-Based Cryptography Specification Version 2.1 [RFC8018]) 436 MUST be 16 octets for the AES Session-key used for encryption and 32 437 octets for the HMAC-SHA1 Session-key used for authentication; see 438 also Section 6.10 of OWAMP [RFC4656]. 440 Each client container also holds a list of control connections, where 441 each item in the list describes a TWAMP control connection initiated 442 by this Control-Client. There SHALL be one ctrl-connection per 443 TWAMP-Control (TCP) connection that is to be initiated from this 444 device. 446 In turn, each ctrl-connection holds a list of test-session-request. 447 test-session-request holds information associated with the Control- 448 Client for this test session. This includes information associated 449 with the Request-TW-Session/Accept-Session message exchange (see 450 Section 3.5 of TWAMP [RFC5357]). 452 There SHALL be one instance of test-session-request for each TWAMP- 453 Test session that is to be negotiated by this TWAMP-Control 454 connection via a Request-TW-Session/Accept-Session exchange. 456 The Control-Client is also responsible for scheduling TWAMP-Test 457 sessions so test-session-request holds information related to these 458 actions (e.g. pm-index, repeat-interval). 460 4.2. Server 462 The server container (see Figure 4) holds items that are related to 463 the configuration of the TWAMP Server logical entity (recall 464 Figure 1). 466 The server container includes an administrative configuration 467 parameter (server/admin-state) that indicates whether the device is 468 allowed to receive TWAMP-Control connections. 470 A device operating in the Server role cannot configure attributes on 471 a per TWAMP-Control connection basis, as it has no foreknowledge of 472 the incoming TWAMP-Control connections to be received. Consequently, 473 any parameter that the Server might want to apply to an incoming 474 control connection must be configured at the overall Server level and 475 applied to all incoming TWAMP-Control connections. 477 +---------------------+ 478 | server | 479 +---------------------+ 480 | admin-state | 1..* +------------+ 481 | server-tcp-port |<>------| key-chain | 482 | servwait | +------------+ 483 | control-packet-dscp | | key-id | 484 | count | | secret-key | 485 | max-count | +------------+ 486 | modes | 487 | | 0..* +--------------------------+ 488 | |<>------| ctrl-connection | 489 +---------------------+ +--------------------------+ 490 | client-ip {ro} | 491 | client-tcp-port {ro} | 492 | server-ip {ro} | 493 | server-tcp-port {ro} | 494 | state {ro} | 495 | control-packet-dscp {ro} | 496 | selected-mode {ro} | 497 | key-id {ro} | 498 | count {ro} | 499 | max-count {ro} | 500 | salt {ro} | 501 | server-iv {ro} | 502 | challenge {ro} | 503 +--------------------------+ 505 Figure 4: TWAMP Server UML class diagram 507 Each server container holds a list named key-chain which relates 508 KeyIDs with the respective secret keys. As mentioned in Section 4.1, 509 both the Server and the Control-Client use the same mappings from 510 KeyIDs to shared secrets. The Server, being prepared to conduct 511 sessions with more than one Control-Client, uses KeyIDs to choose the 512 appropriate secret-key; a Control-Client would typically have 513 different secret keys for different Servers. key-id tells the Server 514 which shared-secret the Control-Client wishes to use for 515 authentication or encryption. 517 Each incoming control connection active on the Server is represented 518 by a ctrl-connection. There SHALL be one ctrl-connection per 519 incoming TWAMP-Control (TCP) connection that is received and active 520 on the Server. Each ctrl-connection can be uniquely identified by 521 the 4-tuple {client-ip, client-tcp-port, server-ip, server-tcp-port}. 522 All items in the ctrl-connection list are read-only. 524 4.3. Session-Sender 526 The session-sender container, illustrated in Figure 5, holds items 527 that are related to the configuration of the TWAMP Session-Sender 528 logical entity. 530 The session-sender container includes an administrative parameter 531 (session-sender/admin-state) that controls whether the device is 532 allowed to initiate TWAMP-Test sessions. 534 +----------------+ 535 | session-sender | 536 +----------------+ 0..* +---------------------------+ 537 | admin-state |<>-----| test-session | 538 +----------------+ +---------------------------+ 539 | name | 540 | ctrl-connection-name {ro} | 541 | fill-mode | 542 | number-of-packets | 543 | state {ro} | 544 | sent-packets {ro} | 545 | rcv-packets {ro} | 546 | last-sent-seq {ro} | 547 | last-rcv-seq {ro} | 548 +---------------------------+ 549 ^ 550 V 551 | 1 552 +---------------------+ 553 | packet-distribution | 554 +---------------------+ 555 | periodic / poisson | 556 +---------------------+ 557 | | 558 +-------------------+ | 559 | periodic-interval | | 560 +-------------------+ | 561 | 562 +--------------+ 563 | lambda | 564 | max-interval | 565 +--------------+ 567 Figure 5: TWAMP Session-Sender UML class diagram 569 Each TWAMP-Test session initiated by the Session-Sender will be 570 represented by an instance of a test-session object. There SHALL be 571 one instance of test-session for each TWAMP-Test session for which 572 packets are being sent. 574 4.4. Session-Reflector 576 The session-reflector container, illustrated in Figure 6, holds items 577 that are related to the configuration of the TWAMP Session-Reflector 578 logical entity. 580 The session-reflector container includes an administrative parameter 581 (session-reflector/admin-state) that controls whether the device is 582 allowed to respond to incoming TWAMP-Test sessions. 584 A device operating in the Session-Reflector role cannot configure 585 attributes on a per-session basis, as it has no foreknowledge of what 586 incoming sessions it will receive. As such, any parameter that the 587 Session-Reflector might want to apply to an incoming TWAMP-Test 588 session must be configured at the overall Session-Reflector level and 589 are applied to all incoming sessions. 591 +----=--------------+ 592 | session-reflector | 593 +-------------------+ 594 | admin-state | 595 | refwait | 596 +-------------------+ 597 ^ 598 V 599 | 600 | 0..* 601 +----------------------------------------+ 602 | test-session | 603 +----------------------------------------+ 604 | sid {ro} | 605 | sender-ip {ro} | 606 | sender-udp-port {ro} | 607 | reflector-ip {ro} | 608 | reflector-udp-port {ro} | 609 | parent-connection-client-ip {ro} | 610 | parent-connection-client-tcp-port {ro} | 611 | parent-connection-server-ip {ro} | 612 | parent-connection-server-tcp-port {ro} | 613 | test-packet-dscp {ro} | 614 | sent-packets {ro} | 615 | rcv-packets {ro} | 616 | last-sent-seq {ro} | 617 | last-rcv-seq {ro} | 618 +----------------------------------------+ 620 Figure 6: TWAMP Session-Reflector UML class diagram 622 Each incoming TWAMP-Test session that is active on the Session- 623 Reflector SHALL be represented by an instance of a test-session 624 object. All items in the test-session object are read-only. 626 Instances of test-session are indexed by a session identifier (sid). 627 This value is auto-allocated by the TWAMP Server as test session 628 requests are received, and communicated back to the Control-Client in 629 the SID field of the Accept-Session message; see Section 4.3 of TWAMP 630 Reflect Octets and Symmetrical Size Features [RFC6038]. 632 When attempting to retrieve operational data for active test sessions 633 from a Session-Reflector device, the user will not know what sessions 634 are currently active on that device, or what SIDs have been auto- 635 allocated for these test sessions. If the user has network access to 636 the Control-Client device, then it is possible to read the data for 637 this session under client/ctrl-connection/test-session-request/sid 638 and obtain the SID (see Figure 3). The user may then use this SID 639 value as an index to retrieve an individual session-reflector/test- 640 session instance on the Session-Reflector device. 642 If the user has no network access to the Control-Client device, then 643 the only option is to retrieve all test-session instances from the 644 Session-Reflector device, and then pick out specific test-session 645 instances of interest to the user. This could be problematic if a 646 large number of test sessions are currently active on that device. 648 Each Session-Reflector TWAMP-Test session contains the following 649 4-tuple: {parent-connection-client-ip, parent-connection-client-tcp- 650 port, parent-connection-server-ip, parent-connection-server-tcp- 651 port}. This 4-tuple MUST correspond to the equivalent 4-tuple 652 {client-ip, client-tcp-port, server-ip, server-tcp-port} in server/ 653 ctrl-connection. This 4-tuple allows the user to trace back from the 654 TWAMP-Test session to the (parent) TWAMP-Control connection that 655 negotiated this test session. 657 5. Data Model 659 This section formally specifies the TWAMP data model using YANG. 661 5.1. YANG Tree Diagram 663 This section presents a simplified graphical representation of the 664 TWAMP data model using a YANG tree diagram. Readers should keep in 665 mind that the limit of 72 characters per line forces us to introduce 666 artificial line breaks in some tree diagram nodes. Tree diagrams 667 used in this document follow the notation defined in YANG Tree 668 Diagrams [RFC8340]. 670 module: ietf-twamp 671 +--rw twamp 672 +--rw client {control-client}? 673 | +--rw admin-state? boolean 674 | +--rw mode-preference-chain* [priority] 675 | | +--rw priority uint16 676 | | +--rw mode? twamp-modes 677 | +--rw key-chain* [key-id] 678 | | +--rw key-id string 679 | | +--rw secret-key? string 680 | +--rw ctrl-connection* [name] 681 | +--rw name string 682 | +--rw client-ip? inet:ip-address 683 | +--rw server-ip inet:ip-address 684 | +--rw server-tcp-port? inet:port-number 685 | +--rw control-packet-dscp? inet:dscp 686 | +--rw key-id? string 687 | +--rw max-count? uint8 688 | +--ro client-tcp-port? inet:port-number 689 | +--ro server-start-time? uint64 690 | +--ro repeat-count? uint64 691 | +--ro state? 692 | | control-client-connection-state 693 | +--ro selected-mode? twamp-modes 694 | +--ro token? binary 695 | +--ro client-iv? binary 696 | +--rw test-session-request* [name] 697 | +--rw name string 698 | +--rw sender-ip? inet:ip-address 699 | +--rw sender-udp-port? union 700 | +--rw reflector-ip inet:ip-address 701 | +--rw reflector-udp-port? inet:port-number 702 | +--rw timeout? uint64 703 | +--rw padding-length? uint32 704 | +--rw test-packet-dscp? inet:dscp 705 | +--rw start-time? uint64 706 | +--rw repeat? union 707 | +--rw repeat-interval? uint32 708 | +--rw pm-reg-list* [pm-index] 709 | | +--rw pm-index uint16 710 | +--ro state? test-session-state 711 | +--ro sid? string 712 +--rw server {server}? 713 | +--rw admin-state? boolean 714 | +--rw server-tcp-port? inet:port-number 715 | +--rw servwait? uint32 716 | +--rw control-packet-dscp? inet:dscp 717 | +--rw count? uint8 718 | +--rw max-count? uint8 719 | +--rw modes? twamp-modes 720 | +--rw key-chain* [key-id] 721 | | +--rw key-id string 722 | | +--rw secret-key? string 723 | +--ro ctrl-connection* 724 | [client-ip client-tcp-port server-ip server-tcp-port] 725 | +--ro client-ip inet:ip-address 726 | +--ro client-tcp-port inet:port-number 727 | +--ro server-ip inet:ip-address 728 | +--ro server-tcp-port inet:port-number 729 | +--ro state? server-ctrl-connection-state 730 | +--ro control-packet-dscp? inet:dscp 731 | +--ro selected-mode? twamp-modes 732 | +--ro key-id? string 733 | +--ro count? uint8 734 | +--ro max-count? uint8 735 | +--ro salt? binary 736 | +--ro server-iv? binary 737 | +--ro challenge? binary 738 +--rw session-sender {session-sender}? 739 | +--rw admin-state? boolean 740 | +--rw test-session* [name] 741 | +--rw name string 742 | +--ro ctrl-connection-name? string 743 | +--rw fill-mode? padding-fill-mode 744 | +--rw number-of-packets uint32 745 | +--rw (packet-distribution)? 746 | | +--:(periodic) 747 | | | +--rw periodic-interval decimal64 748 | | +--:(poisson) 749 | | +--rw lambda decimal64 750 | | +--rw max-interval? decimal64 751 | +--ro state? sender-session-state 752 | +--ro sent-packets? uint32 753 | +--ro rcv-packets? uint32 754 | +--ro last-sent-seq? uint32 755 | +--ro last-rcv-seq? uint32 756 +--rw session-reflector {session-reflector}? 757 +--rw admin-state? boolean 758 +--rw refwait? uint32 759 +--ro test-session* 760 [sender-ip sender-udp-port reflector-ip reflector-udp 761 -port] 762 +--ro sid? string 763 +--ro sender-ip inet:ip-address 764 +--ro sender-udp-port 765 | dynamic-port-number 766 +--ro reflector-ip inet:ip-address 767 +--ro reflector-udp-port inet:port-numbe 768 r 769 +--ro parent-connection-client-ip? inet:ip-address 770 +--ro parent-connection-client-tcp-port? inet:port-numbe 771 r 772 +--ro parent-connection-server-ip? inet:ip-address 773 +--ro parent-connection-server-tcp-port? inet:port-numbe 774 r 775 +--ro test-packet-dscp? inet:dscp 776 +--ro sent-packets? uint32 777 +--ro rcv-packets? uint32 778 +--ro last-sent-seq? uint32 779 +--ro last-rcv-seq? uint32 781 Figure 7: YANG Tree Diagram. 783 5.2. YANG Module 785 This section presents the YANG module for the TWAMP data model 786 defined in this document. The module imports definitions from NTPv3 787 Specification [RFC1305], Randomness Requirements for Security 788 [RFC4086], OWAMP [RFC4656], TWAMP [RFC5357], More Features for TWAMP 789 [RFC5618], Individual Session Control Feature [RFC5938], TWAMP 790 Reflect Octets and Symmetrical Size Features [RFC6038], Common YANG 791 Data Types [RFC6991], Advances Stream and Sampling Framework 792 [RFC7312], IKEv2-Derived Shared Secret Key for OWAMP and TWAMP 793 [RFC7717], and OWAMP and TWAMP Well-Known Port Assignments 794 [I-D.ietf-ippm-port-twamp-test]. 796 file "ietf-twamp@2018-04-16.yang" 798 module ietf-twamp { 799 yang-version 1.1; 800 namespace urn:ietf:params:xml:ns:yang:ietf-twamp; 801 prefix ietf-twamp; 803 import ietf-inet-types { 804 prefix inet; 805 reference 806 "RFC 6991: Common YANG Types."; 807 } 809 organization 810 "IETF IPPM (IP Performance Metrics) Working Group"; 812 contact 813 "WG Web: http://tools.ietf.org/wg/ippm/ 814 WG List: ippm@ietf.org 816 Editor: Ruth Civil 817 gcivil@ciena.com 818 Editor: Al Morton 819 acmorton@att.com 820 Editor: Reshad Rehman 821 rrahman@cisco.com 822 Editor: Mahesh Jethanandani 823 mjethanandani@gmail.com 824 Editor: Kostas Pentikousis 825 k.pentikousis@travelping.com"; 827 description 828 "This YANG module specifies a vendor-independent data 829 model for the Two-Way Active Measurement Protocol (TWAMP). 831 The data model covers four TWAMP logical entities, namely, 832 Control-Client, Server, Session-Sender, and Session-Reflector, 833 as illustrated in the annotated TWAMP logical model (Fig. 1 834 of RFC XXXX). 836 This YANG module uses features to indicate which of the four 837 logical entities are supported by a TWAMP implementation. 839 Copyright (c) 2018 IETF Trust and the persons identified as 840 the document authors. All rights reserved. 841 Redistribution and use in source and binary forms, with or 842 without modification, is permitted pursuant to, and subject 843 to the license terms contained in, the Simplified BSD 844 License set forth in Section 4.c of the IETF Trust's Legal 845 Provisions Relating to IETF Documents 846 (http://trustee.ietf.org/license-info). 848 This version of this YANG module is part of RFC XXXX; see 849 the RFC itself for full legal notices."; 851 revision 2018-04-16 { 852 description 853 "Initial Revision. 855 Covers RFC 5357, RFC 5618, RFC 5938, RFC 6038, RFC 7717, and 856 draft-ietf-ippm-metric-registry"; 858 reference 859 "RFC XXXX: TWAMP YANG Data Model."; 860 } 862 /* 863 * Typedefs 864 */ 866 typedef twamp-modes { 867 type bits { 868 bit unauthenticated { 869 position 0; 870 description 871 "Unauthenticated mode, in which no encryption or 872 authentication is applied in TWAMP-Control and 873 TWAMP-Test. KeyID, Token, and Client-IV are not used in 874 the Set-Up-Response message. See Section 3.1 of 875 RFC 4656."; 876 reference 877 "RFC 4656: A One-way Active Measurement Protocol 878 (OWAMP)"; 879 } 880 bit authenticated { 881 position 1; 882 description 883 "Authenticated mode, in which the Control-Client and 884 Server possess a shared secret thus prohibiting 885 'theft of service'. As per Section 6 of RFC 4656, 886 in 'authenticated mode, the timestamp is in the clear 887 and is not protected cryptographically in any way, 888 while the rest of the message has the same protection 889 as in encrypted mode. This mode allows one to trade off 890 cryptographic protection against accuracy of 891 timestamps.'"; 892 reference 893 "RFC 4656: A One-way Active Measurement Protocol 894 (OWAMP)"; 895 } 896 bit encrypted { 897 position 2; 898 description 899 "Encrypted mode 'makes it impossible to alter 900 timestamps undetectably.' See also Section 4 of RFC 7717 901 and Section 6 of RFC 4656."; 902 reference 903 "RFC 4656: A One-way Active Measurement Protocol 904 (OWAMP)"; 905 } 906 bit unauth-test-encrpyt-control { 907 position 3; 908 description 909 "When using the Mixed Security Mode, the TWAMP-Test 910 protocol follows the Unauthenticated mode and the 911 TWAMP-Control protocol the Encrypted mode."; 912 reference 913 "RFC 5618: Mixed Security Mode for the Two-Way Active 914 Measurement Protocol (TWAMP)"; 915 } 916 bit individual-session-control { 917 position 4; 918 description 919 "This mode enables individual test sessions using 920 Session Identifiers."; 921 reference 922 "RFC 5938: Individual Session Control Feature 923 for the Two-Way Active Measurement Protocol (TWAMP)"; 924 } 925 bit reflect-octets { 926 position 5; 927 description 928 "This mode indicates the reflect octets capability."; 929 reference 930 "RFC 6038: Two-Way Active Measurement Protocol (TWAMP) 931 Reflect Octets and Symmetrical Size Features"; 932 } 933 bit symmetrical-size { 934 position 6; 935 description 936 "This mode indicates support for the symmetrical size 937 sender test packet format."; 938 reference 939 "RFC 6038: Two-Way Active Measurement Protocol (TWAMP) 940 Reflect Octets and Symmetrical Size Features"; 941 } 942 bit IKEv2Derived { 943 position 7; 944 description 945 "In this mode the the shared key is derived 946 from an IKEv2 security association (SA)."; 947 reference 948 "RFC 7717: IKEv2-Derived Shared Secret Key for 949 the One-Way Active Measurement Protocol (OWAMP) 950 and Two-Way Active Measurement Protocol (TWAMP)"; 951 } 952 } 953 description 954 "Specifies the configurable TWAMP-Modes supported during a 955 TWAMP-Control Connection setup between a Control-Client 956 and a Server. Section 7 of RFC 7717 summarizes the 957 TWAMP-Modes registry and points to their formal 958 specification."; 959 } 961 typedef control-client-connection-state { 962 type enumeration { 963 enum active { 964 description 965 "Indicates an active TWAMP-Control connection to 966 Server."; 967 } 968 enum idle { 969 description 970 "Indicates an idle TWAMP-Control connection to Server."; 971 } 972 } 973 description 974 "Indicates the Control-Client TWAMP-Control connection 975 state."; 976 } 978 typedef test-session-state { 979 type enumeration { 980 enum accepted { 981 value 0; 982 description 983 "Indicates an accepted TWAMP-Test session request."; 984 } 985 enum failed { 986 value 1; 987 description 988 "Indicates a TWAMP-Test session failure due to 989 some unspecified reason (catch-all)."; 990 } 991 enum internal-error { 992 value 2; 993 description 994 "Indicates a TWAMP-Test session failure due to 995 an internal error."; 996 } 997 enum not-supported { 998 value 3; 999 description 1000 "Indicates a TWAMP-Test session failure because 1001 some aspect of the TWAMP-Test session request 1002 is not supported."; 1003 } 1004 enum permanent-resource-limit { 1005 value 4; 1006 description 1007 "Indicates a TWAMP-Test session failure due to 1008 permanent resource limitations."; 1009 } 1010 enum temp-resource-limit { 1011 value 5; 1012 description 1013 "Indicates a TWAMP-Test session failure due to 1014 temporary resource limitations."; 1015 } 1016 } 1017 description 1018 "Indicates the Control-Client TWAMP-Test session state."; 1019 } 1021 typedef server-ctrl-connection-state { 1022 type enumeration { 1023 enum active { 1024 description 1025 "Indicates an active TWAMP-Control connection 1026 to the Control-Client."; 1027 } 1028 enum servwait { 1029 description 1030 "Indicates that the TWAMP-Control connection to the 1031 Control-Client is in SERVWAIT as per the definition of 1032 Section 3.1 of RFC 5357."; 1033 } 1034 } 1035 description 1036 "Indicates the Server TWAMP-Control connection state."; 1037 } 1039 typedef sender-session-state { 1040 type enumeration { 1041 enum active { 1042 description 1043 "Indicates that the TWAMP-Test session is active."; 1044 } 1045 enum failure { 1046 description 1047 "Indicates that the TWAMP-Test session has failed."; 1048 } 1049 } 1050 description 1051 "Indicates the Session-Sender TWAMP-Test session state."; 1052 } 1054 typedef padding-fill-mode { 1055 type enumeration { 1056 enum zero { 1057 description 1058 "TWAMP-Test packets are padded with all zeros."; 1059 } 1060 enum random { 1061 description 1062 "TWAMP-Test packets are padded with pseudo-random 1063 numbers."; 1064 } 1065 } 1066 description 1067 "Indicates what type of packet padding is used in the 1068 TWAMP-Test packets."; 1069 } 1070 typedef dynamic-port-number { 1071 type inet:port-number { 1072 range 49152..65535; 1073 } 1074 description "Dynamic range for port numbers."; 1075 } 1077 /* 1078 * Features 1079 */ 1081 feature control-client { 1082 description 1083 "Indicates that the device supports configuration of the 1084 TWAMP Control-Client logical entity."; 1085 } 1087 feature server { 1088 description 1089 "Indicates that the device supports configuration of the 1090 TWAMP Server logical entity."; 1091 } 1093 feature session-sender { 1094 description 1095 "Indicates that the device supports configuration of the 1096 TWAMP Session-Sender logical entity."; 1097 } 1099 feature session-reflector { 1100 description 1101 "Indicates that the device supports configuration of the 1102 TWAMP Session-Reflector logical entity."; 1103 } 1105 /* 1106 * Reusable node groups 1107 */ 1109 grouping key-management { 1110 list key-chain { 1111 key key-id; 1112 leaf key-id { 1113 type string { 1114 length 1..80; 1115 } 1116 description 1117 "KeyID used for a TWAMP-Control connection. As per 1118 Section 3.1 of RFC 4656, KeyID is 'a UTF-8 string, up to 1119 80 octets in length' and is used to select which 'shared 1120 shared secret the [Control-Client] wishes to use to 1121 authenticate or encrypt'."; 1122 } 1123 leaf secret-key { 1124 type string; 1125 description 1126 "The secret key corresponding to the KeyID for this 1127 TWAMP-Control connection."; 1128 } 1129 description 1130 "Relates KeyIDs with their respective secret keys 1131 in a TWAMP-Control connection."; 1132 } 1133 description 1134 "Used by the Control-Client and Server for TWAMP-Control 1135 key management."; 1136 } 1138 grouping maintenance-statistics { 1139 leaf sent-packets { 1140 type uint32; 1141 config false; 1142 description 1143 "Indicates the number of packets sent."; 1144 } 1146 leaf rcv-packets { 1147 type uint32; 1148 config false; 1149 description 1150 "Indicates the number of packets received."; 1151 } 1153 leaf last-sent-seq { 1154 type uint32; 1155 config false; 1156 description 1157 "Indicates the last sent sequence number."; 1158 } 1160 leaf last-rcv-seq { 1161 type uint32; 1162 config false; 1163 description 1164 "Indicates the last received sequence number."; 1166 } 1167 description 1168 "Used for TWAMP-Test maintenance statistics."; 1169 } 1171 grouping count { 1172 leaf count { 1173 type uint8 { 1174 range "10..31"; 1175 } 1176 default 10; 1177 description 1178 "Parameter communicated to the Control-Client as part of 1179 the Server Greeting message and used for deriving a key 1180 from a shared secret as per Section 3.1 of RFC 4656: 1181 MUST be a power of 2 and at least 1024. It is configured 1182 by providing said power. For example, configuring 15 here 1183 means count 2^15 = 32768. The default is 10, 1184 meaning 2^10 = 1024."; 1185 } 1186 description 1187 "Reusable data structure for count, which is used both in the 1188 Server and the Control-Client."; 1189 } 1191 grouping max-count-exponent { 1192 leaf max-count { 1193 type uint8 { 1194 range 10..31; 1195 } 1196 default 15; 1197 description 1198 "This parameter limits the maximum Count value, which MUST 1199 be a power of 2 and at least 1024 as per RFC 5357. It is 1200 configured by providing said power. For example, 1201 configuring 10 here means max count 2^10 = 1024. 1202 The default is 15, meaning 2^15 = 32768. 1204 A TWAMP Server uses this configured value in the 1205 Server-Greeting message sent to the Control-Client. 1207 A TWAMP Control-Client uses this configured value to 1208 prevent denial-of-service (DOS) attacks by closing the 1209 control connection to the Server if it 'receives a 1210 Server-Greeting message with Count greater that its 1211 maximum configured value', as per Section 6 of RFC 5357. 1213 Further, note that according to Section 6 of RFC 5357: 1215 'If an attacking system sets the maximum value in 1216 Count (2**32), then the system under attack would stall 1217 for a significant period of time while it attempts to 1218 generate keys. 1220 TWAMP-compliant systems SHOULD have a configuration 1221 control to limit the maximum count value. The default 1222 max-count value SHOULD be 32768.' 1224 RFC 5357 does not qualify 'significant period' in terms of 1225 time, but it is clear that this depends on the processing 1226 capacity available and operators need to pay attention to 1227 this security consideration."; 1228 } 1229 description 1230 "Reusable data structure for max-count which is used both at 1231 the Control-Client and the Server containers."; 1232 } 1234 /* 1235 * Configuration data nodes 1236 */ 1238 container twamp { 1239 description 1240 "TWAMP logical entity configuration grouping of four models 1241 which correspond to the four TWAMP logical entities 1242 Control-Client, Server, Session-Sender, and Session-Reflector 1243 as illustrated in Fig. 1 of RFC XXXX."; 1245 container client { 1246 if-feature control-client; 1247 description 1248 "Configuration of the TWAMP Control-Client logical 1249 entity."; 1251 leaf admin-state { 1252 type boolean; 1253 default true; 1254 description 1255 "Indicates whether the device is allowed to operate as a 1256 TWAMP Control-Client."; 1257 } 1259 list mode-preference-chain { 1260 key priority; 1261 unique mode; 1262 leaf priority { 1263 type uint16; 1264 description 1265 "Indicates the Control-Client Mode preference priority 1266 expressed as a 16-bit unsigned integer, where zero is 1267 the highest priority and subsequent values 1268 monotonically increasing."; 1269 } 1270 leaf mode { 1271 type twamp-modes; 1272 description 1273 "The supported TWAMP Mode matching the corresponding 1274 priority."; 1276 } 1277 description 1278 "Indicates the Control-Client preferred order of use of 1279 the supported TWAMP Modes. 1281 Depending on the Modes available in the TWAMP Server 1282 Greeting message (see Fig. 2 of RFC 7717), the 1283 this Control-Client MUST choose the highest priority 1284 Mode from the configured mode-preference-chain list."; 1285 } 1287 uses key-management; 1289 list ctrl-connection { 1290 key name; 1291 description 1292 "List of TWAMP Control-Client control connections. 1293 Each item in the list describes a control connection 1294 that will be initiated by this Control-Client"; 1296 leaf name { 1297 type string; 1298 description 1299 "A unique name used as a key to identify this 1300 individual TWAMP-Control connection on the 1301 Control-Client device."; 1302 } 1303 leaf client-ip { 1304 type inet:ip-address; 1305 description 1306 "The IP address of the local Control-Client device, 1307 to be placed in the source IP address field of the 1308 IP header in TWAMP-Control (TCP) packets belonging 1309 to this control connection. If not configured, the 1310 device SHALL choose its own source IP address."; 1311 } 1312 leaf server-ip { 1313 type inet:ip-address; 1314 mandatory true; 1315 description 1316 "The IP address of the remote Server device, which the 1317 TWAMP-Control connection will be initiated to."; 1318 } 1320 leaf server-tcp-port { 1321 type inet:port-number; 1322 default 862; 1323 description 1324 "This parameter defines the TCP port number that is 1325 to be used by this outgoing TWAMP-Control connection. 1326 Typically, this is the well-known TWAMP-Control 1327 port number (862) as per RFC 5357 However, there are 1328 known realizations of TWAMP in the field that were 1329 implemented before this well-known port number was 1330 allocated. These early implementations allowed the 1331 port number to be configured. This parameter is 1332 therefore provided for backward compatibility 1333 reasons."; 1334 } 1336 leaf control-packet-dscp { 1337 type inet:dscp; 1338 default 0; 1339 description 1340 "The DSCP value to be placed in the IP header of 1341 TWAMP-Control (TCP) packets generated by this 1342 Control-Client."; 1343 } 1345 leaf key-id { 1346 type string { 1347 length 1..80; 1348 } 1349 description 1350 "Indicates the KeyID value selected for this 1351 TWAMP-Control connection."; 1352 } 1354 uses max-count-exponent; 1356 leaf client-tcp-port { 1357 type inet:port-number; 1358 config false; 1359 description 1360 "Indicates the source TCP port number used in the 1361 TWAMP-Control packets belonging to this control 1362 connection."; 1363 } 1365 leaf server-start-time { 1366 type uint64; 1367 config false; 1368 description 1369 "Indicates the Start-Time advertized by the Server in 1370 the Server-Start message (RFC 4656, Section 3.1), 1371 representing the time when the current 1372 instantiation of the Server started operating. 1373 The timestamp format follows RFC 1305 1374 according to Section 4.1.2 of RFC 4656."; 1375 reference 1376 "RFC 4656: OWAMP, Section 3.1 and 4.1.2, 1377 RFC 1305: NTPv3 Specification."; 1378 } 1380 leaf repeat-count { 1381 type uint64; 1382 config false; 1383 description 1384 "Indicates how many times the test session has been 1385 repeated. When a test is running, this value will be 1386 greater than 0. If the repeat parameter is non-zero, 1387 this value is smaller than or equal to the repeat 1388 parameter."; 1389 } 1390 leaf state { 1391 type control-client-connection-state; 1392 config false; 1393 description 1394 "Indicates the current state of the TWAMP-Control 1395 connection state."; 1396 } 1398 leaf selected-mode { 1399 type twamp-modes; 1400 config false; 1401 description 1402 "The TWAMP Mode that the Control-Client has chosen for 1403 this control connection as set in the Mode field of 1404 the Set-Up-Response message"; 1405 reference 1406 "RFC 4656, Section 3.1."; 1407 } 1409 leaf token { 1410 type binary { 1411 length 64; 1412 } 1413 config false; 1414 description 1415 "This parameter holds the 64 octets containing the 1416 concatenation of a 16-octet Challenge, a 16-octet AES 1417 Session-key used for encryption, and a 32-octet 1418 HMAC-SHA1 Session-key used for authentication; see 1419 also the last paragraph of Section 6 in RFC 4656. 1421 If the Mode defined in RFC 7717 is selected 1422 (selected-mode), Token is limited to 16 octets."; 1423 reference 1424 "RFC 4086: Randomness Requirements for Security 1426 RFC 7717: IKEv2-Derived Shared Secret Key for the 1427 One-Way Active Measurement Protocol (OWAMP) and 1428 Two-Way Active Measurement Protocol (TWAMP)"; 1429 } 1431 leaf client-iv { 1432 type binary { 1433 length 16; 1434 } 1435 config false; 1436 description 1437 "Indicates the Control-Client Initialization Vector 1438 (Client-IV), that is generated randomly by the 1439 Control-Client. As per RFC 4656: 1441 Client-IV merely needs to be unique (i.e., it MUST 1442 never be repeated for different sessions using the 1443 same secret key; a simple way to achieve that without 1444 the use of cumbersome state is to generate the 1445 Client-IV values using a cryptographically secure 1446 pseudo-random number source. 1448 If the Mode defined in RFC 7717 is selected 1449 (selected-mode), Client-IV is limited to 12 octets."; 1450 reference 1451 "RFC 4656: A One-way Active Measurement Protocol 1452 (OWAMP). 1454 RFC 7717: IKEv2-Derived Shared Secret Key for the 1455 One-Way Active Measurement Protocol (OWAMP) and 1456 Two-Way Active Measurement Protocol (TWAMP)"; 1457 } 1459 list test-session-request { 1460 key name; 1461 description 1462 "Information associated with the Control-Client 1463 for this test session"; 1465 leaf name { 1466 type string; 1467 description 1468 "A unique name to be used for identification of 1469 this TWAMP-Test session on the Control-Client."; 1470 } 1472 leaf sender-ip { 1473 type inet:ip-address; 1474 description 1475 "The IP address of the Session-Sender device, 1476 which is to be placed in the source IP address 1477 field of the IP header in TWAMP-Test (UDP) packets 1478 belonging to this test session. This value will be 1479 used to populate the sender address field of the 1480 Request-TW-Session message. 1482 If not configured, the device SHALL choose its own 1483 source IP address."; 1484 } 1486 leaf sender-udp-port { 1487 type union { 1488 type dynamic-port-number; 1489 type enumeration { 1490 enum autoallocate { 1491 description 1492 "Indicates that the Contol-Client will 1493 auto-allocate the TWAMP-Test (UDP) port number 1494 from the dynamic port range."; 1495 } 1496 } 1497 } 1498 default autoallocate; 1499 description 1500 "The UDP port number that is to be used by 1501 the Session-Sender for this TWAMP-Test session. 1503 The number is restricted to the dynamic port range. 1505 By default the Control-Client SHALL auto-allocate a 1506 UDP port number for this TWAMP-Test session. 1508 The configured (or auto-allocated) value is 1509 advertized in the Sender Port field of the 1510 Request-TW-session message (see Section 3.5 of 1511 RFC 5357). Note that in the scenario where a device 1512 auto-allocates a UDP port number for a session, and 1513 the repeat parameter for that session indicates that 1514 it should be repeated, the device is free to 1515 auto-allocate a different UDP port number when it 1516 negotiates the next (repeated) iteration of this 1517 session."; 1518 } 1520 leaf reflector-ip { 1521 type inet:ip-address; 1522 mandatory true; 1523 description 1524 "The IP address belonging to the remote 1525 Session-Reflector device to which the TWAMP-Test 1526 session will be initiated. This value will be 1527 used to populate the receiver address field of 1528 the Request-TW-Session message."; 1529 } 1531 leaf reflector-udp-port { 1532 type inet:port-number { 1533 range "862 | 49152..65535"; 1534 } 1535 description 1536 "This parameter defines the UDP port number that 1537 will be used by the Session-Reflector for 1538 this TWAMP-Test session. The default number is 1539 within the dynamic port range and is to be placed 1540 in the Receiver Port field of the Request-TW-Session 1541 message. The well-known port (862) MAY be 1542 used."; 1543 reference 1544 "draft-ietf-ippm-port-twamp-test: OWAMP and TWAMP 1545 Well-Known Port Assignments."; 1546 } 1548 leaf timeout { 1549 type uint64; 1550 units seconds; 1551 default 2; 1552 description 1553 "The length of time (in seconds) that the 1554 Session-Reflector should continue to respond to 1555 packets belonging to this TWAMP-Test session after 1556 a Stop-Sessions TWAMP-Control message has been 1557 received. 1559 This value will be placed in the Timeout field of 1560 the Request-TW-Session message."; 1561 reference 1562 "RFC 5357: TWAMP, Section 3.8"; 1563 } 1565 leaf padding-length { 1566 type uint32 { 1567 range 64..4096; 1568 } 1569 description 1570 "The number of padding bytes to be added to the 1571 TWAMP-Test (UDP) packets generated by the 1572 Session-Sender. 1574 This value will be placed in the Padding Length 1575 field of the Request-TW-Session message."; 1576 reference 1577 "RFC 4656, Section 3.5."; 1578 } 1580 leaf test-packet-dscp { 1581 type inet:dscp; 1582 default 0; 1583 description 1584 "The DSCP value to be placed in the IP header 1585 of TWAMP-Test packets generated by the 1586 Session-Sender, and in the UDP header of the 1587 TWAMP-Test response packets generated by the 1588 Session-Reflector for this test session. 1590 This value will be placed in the Type-P Descriptor 1591 field of the Request-TW-Session message"; 1592 reference 1593 "RFC 5357."; 1594 } 1596 leaf start-time { 1597 type uint64; 1598 default 0; 1599 description 1600 "Time when the session is to be started 1601 (but not before the TWAMP Start-Sessions command 1602 is issued; see Section 3.4 of RFC 5357). 1604 The start-time value is placed in the Start Time 1605 field of the Request-TW-Session message. 1607 The timestamp format follows RFC 1305 as per 1608 Section 3.5 of RFC 4656. 1610 The default value of 0 indicates that the session 1611 will be started as soon as the Start-Sessions 1612 message is received."; 1613 } 1615 leaf repeat { 1616 type union { 1617 type uint32 { 1618 range 0..4294967294; 1619 } 1620 type enumeration { 1621 enum forever { 1622 description 1623 "Indicates that the test session SHALL be 1624 repeated *forever* using the information in 1625 repeat-interval parameter, and SHALL NOT 1626 decrement the value."; 1627 } 1628 } 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."; 1645 } 1646 leaf repeat-interval { 1647 when "../repeat!='0'" { 1648 description 1649 "This parameter determines the timing of repeated 1650 TWAMP-Test sessions when repeat is more than 0. 1652 When the value of repeat-interval is 0, the 1653 negotiation of a new test session SHALL begin 1654 immediately after the previous test session 1655 completes. Otherwise, the Control-Client will 1656 wait for the number of seconds specified in the 1657 repeat-interval parameter before negotiating the 1658 new instance of this TWAMP-Test session."; 1659 } 1660 type uint32; 1661 units seconds; 1662 default 0; 1663 description 1664 "Repeat interval (in seconds)."; 1665 } 1667 list pm-reg-list { 1668 key pm-index; 1669 leaf pm-index { 1670 type uint16; 1671 description 1672 "Numerical index value of a Registered Metric 1673 in the Performance Metric Registry 1674 (see ietf-ippm-metric-registry). Output statistics 1675 are specified in the corresponding Registry 1676 entry."; 1677 } 1678 description 1679 "A list of one or more Performance Metric Registry 1680 Index values, which communicate packet stream 1681 characteristics along with one or more metrics 1682 to be measured. 1684 All members of the pm-reg-list MUST have the same 1685 stream characteristics, such that they combine 1686 to specify all metrics that shall be measured on 1687 a single stream."; 1688 reference 1689 "ietf-ippm-metric-registry: Registry for 1690 Performance Metrics"; 1691 } 1693 leaf state { 1694 type test-session-state; 1695 config false; 1696 description 1697 "Indicates the TWAMP-Test session state, accepted or 1698 indication of an error."; 1699 reference 1700 "Section 3.5 of RFC 5357."; 1701 } 1702 leaf sid { 1703 type string; 1704 config false; 1705 description 1706 "The SID allocated by the Server for this TWAMP-Test 1707 session, and communicated back to the Control-Client 1708 in the SID field of the Accept-Session message"; 1709 reference 1710 "Section 4.3 of RFC 6038."; 1711 } 1712 } 1713 } 1714 } 1716 container server { 1717 if-feature server; 1718 description 1719 "Configuration of the TWAMP Server logical entity."; 1721 leaf admin-state { 1722 type boolean; 1723 default true; 1724 description 1725 "Indicates whether the device is allowed to operate 1726 as a TWAMP Server."; 1727 } 1729 leaf server-tcp-port { 1730 type inet:port-number; 1731 default 862; 1732 description 1733 "This parameter defines the well known TCP port number 1734 that is used by TWAMP-Control. The Server will listen 1735 on this port number for incoming TWAMP-Control 1736 connections. Although this is defined as a fixed value 1737 (862) in RFC 5357, there are several realizations of 1738 TWAMP in the field that were implemented before this 1739 well-known port number was allocated. These early 1740 implementations allowed the port number to be 1741 configured. This parameter is therefore provided for 1742 backward compatibility reasons."; 1743 } 1745 leaf servwait { 1746 type uint32 { 1747 range 1..604800; 1748 } 1749 units seconds; 1750 default 900; 1751 description 1752 "TWAMP-Control (TCP) session timeout, in seconds. 1753 According to Section 3.1 of RFC 5357, 1755 Server MAY discontinue any established control 1756 connection when no packet associated with that 1757 connection has been received within SERVWAIT seconds."; 1758 } 1760 leaf control-packet-dscp { 1761 type inet:dscp; 1762 description 1763 "The DSCP value to be placed in the IP header of 1764 TWAMP-Control (TCP) packets generated by the Server. 1766 Section 3.1 of RFC 5357 specifies that the server 1767 SHOULD use the DSCP value from the Control-Clients 1768 TCP SYN. However, for practical purposes TWAMP will 1769 typically be implemented using a general purpose TCP 1770 stack provided by the underlying operating system, 1771 and such a stack may not provide this information to the 1772 user. Consequently, it is not always possible to 1773 implement the behavior described in RFC 5357 in an 1774 OS-portable version of TWAMP. 1776 The default behavior if this item is not set is to use 1777 the DSCP value from the Control-Clients TCP SYN."; 1778 reference 1779 "Section 3.1 of RFC 5357."; 1780 } 1782 uses count; 1784 uses max-count-exponent; 1786 leaf modes { 1787 type twamp-modes; 1788 description 1789 "The bit mask of TWAMP Modes this Server instance 1790 is willing to support; see IANA TWAMP Modes Registry."; 1791 } 1793 uses key-management; 1795 list ctrl-connection { 1796 key "client-ip client-tcp-port server-ip server-tcp-port"; 1797 config false; 1798 description 1799 "List of all incoming TWAMP-Control (TCP) connections."; 1801 leaf client-ip { 1802 type inet:ip-address; 1803 description 1804 "The IP address on the remote Control-Client device, 1805 which is the source IP address used in the 1806 TWAMP-Control (TCP) packets belonging to this control 1807 connection."; 1808 } 1810 leaf client-tcp-port { 1811 type inet:port-number; 1812 description 1813 "The source TCP port number used in the TWAMP-Control 1814 (TCP) packets belonging to this control connection."; 1815 } 1817 leaf server-ip { 1818 type inet:ip-address; 1819 description 1820 "The IP address of the local Server device, which is 1821 the destination IP address used in the 1822 TWAMP-Control (TCP) packets belonging to this control 1823 connection."; 1824 } 1826 leaf server-tcp-port { 1827 type inet:port-number; 1828 description 1829 "The destination TCP port number used in the 1830 TWAMP-Control (TCP) packets belonging to this 1831 control connection. This will usually be the 1832 same value as the server-tcp-port configured 1833 under twamp/server. However, in the event that 1834 the user re-configured server/server-tcp-port 1835 after this control connection was initiated, this 1836 value will indicate the server-tcp-port that is 1837 actually in use for this control connection."; 1839 } 1841 leaf state { 1842 type server-ctrl-connection-state; 1843 description 1844 "Indicates the Server TWAMP-Control connection state."; 1845 } 1847 leaf control-packet-dscp { 1848 type inet:dscp; 1849 description 1850 "The DSCP value used in the IP header of the 1851 TWAMP-Control (TCP) packets sent by the Server 1852 for this control connection. This will usually 1853 be the same value as is configured in the 1854 control-packet-dscp parameter under the twamp/server 1855 container. However, in the event that the user 1856 re-configures server/dscp after this control 1857 connection is already in progress, this read-only 1858 value will show the actual dscp value in use by this 1859 TWAMP-Control connection."; 1860 } 1862 leaf selected-mode { 1863 type twamp-modes; 1864 description 1865 "The Mode that was chosen for this TWAMP-Control 1866 connection as set in the Mode field of the 1867 Set-Up-Response message."; 1868 } 1870 leaf key-id { 1871 type string { 1872 length 1..80; 1873 } 1874 description 1875 "The KeyID value that is in use by this TWAMP-Control 1876 connection as selected by Control-Client."; 1877 } 1879 uses count { 1880 description 1881 "The count value that is in use by this TWAMP-Control 1882 connection. This will usually be the same value 1883 as is configured under twamp/server. However, in the 1884 event that the user re-configured server/count 1885 after this control connection is already in progress, 1886 this read-only value will show the actual count that 1887 is in use for this TWAMP-Control connection."; 1888 } 1890 uses max-count-exponent { 1891 description 1892 "This read-only value indicates the actual max-count in 1893 use for this control connection. Usually this would be 1894 the same value as configured under twamp/server."; 1895 } 1897 leaf salt { 1898 type binary { 1899 length 16; 1900 } 1901 description 1902 "A parameter used in deriving a key from a 1903 shared secret as described in Section 3.1 of RFC 4656. 1904 It is communicated to the Control-Client as part of 1905 the Server Greeting message."; 1906 } 1908 leaf server-iv { 1909 type binary { 1910 length 16; 1911 } 1912 description 1913 "The Server Initialization Vector 1914 (IV) generated randomly by the Server."; 1915 } 1917 leaf challenge { 1918 type binary { 1919 length 16; 1920 } 1921 description 1922 "A random sequence of octets generated by the Server. 1923 As described in client/token, Challenge is used 1924 by the Control-Client to prove possession of a 1925 shared secret."; 1926 } 1927 } 1928 } 1930 container session-sender { 1931 if-feature session-sender; 1932 description 1933 "Configuration of the TWAMP Session-Sender logical entity"; 1934 leaf admin-state { 1935 type boolean; 1936 default true; 1937 description 1938 "Indicates whether the device is allowed to operate 1939 as a TWAMP Session-Sender."; 1940 } 1942 list test-session{ 1943 key name; 1944 description 1945 "List of TWAMP Session-Sender test sessions."; 1947 leaf name { 1948 type string; 1949 description 1950 "A unique name for this TWAMP-Test session to be used 1951 for identifying this test session by the 1952 Session-Sender logical entity."; 1953 } 1955 leaf ctrl-connection-name { 1956 type string; 1957 config false; 1958 description 1959 "The name of the parent TWAMP-Control connection that 1960 is responsible for negotiating this TWAMP-Test 1961 session."; 1962 } 1964 leaf fill-mode { 1965 type padding-fill-mode; 1966 default zero; 1967 description 1968 "Indicates whether the padding added to the 1969 TWAMP-Test (UDP) packets will contain pseudo-random 1970 numbers, or whether it should consist of all zeroes, 1971 as per Section 4.2.1 of RFC 5357."; 1972 } 1974 leaf number-of-packets { 1975 type uint32; 1976 mandatory true; 1977 description 1978 "The overall number of TWAMP-Test (UDP) packets to be 1979 transmitted by the Session-Sender for this test 1980 session."; 1981 } 1982 choice packet-distribution { 1983 description 1984 "Indicates the distribution to be used for transmitting 1985 the TWAMP-Test (UDP) packets."; 1986 case periodic { 1987 leaf periodic-interval { 1988 type decimal64 { 1989 fraction-digits 5; 1990 } 1991 units seconds; 1992 mandatory true; 1993 description 1994 "Indicates the time to wait (in seconds) between 1995 the first bits of TWAMP-Test (UDP) packet 1996 transmissions for this test session."; 1997 reference 1998 "RFC 3432: Network performance measurement 1999 with periodic streams"; 2000 } 2001 } 2002 case poisson { 2003 leaf lambda { 2004 type decimal64 { 2005 fraction-digits 5; 2006 } 2007 units seconds; 2008 mandatory true; 2009 description 2010 "Indicates the average time interval (in seconds) 2011 between packets in the Poisson distribution. 2012 The packet is calculated using the reciprocal of 2013 lambda and the TWAMP-Test packet size (which 2014 depends on the selected Mode and the packet 2015 padding)."; 2016 reference 2017 "RFC 2330: Framework for IP Performance Metrics"; 2018 } 2019 leaf max-interval { 2020 type decimal64 { 2021 fraction-digits 5; 2022 } 2023 units seconds; 2024 description 2025 "Indicates the maximum time (in seconds) 2026 between packet transmissions."; 2027 reference 2028 "RFC 7312: Advanced Stream and Sampling Framework 2029 for IP Performance Metrics (IPPM)"; 2031 } 2032 } 2033 } 2035 leaf state { 2036 type sender-session-state; 2037 config false; 2038 description 2039 "Indicates the Session-Sender test session state."; 2040 } 2042 uses maintenance-statistics; 2043 } 2044 } 2046 container session-reflector { 2047 if-feature session-reflector; 2048 description 2049 "Configuration of the TWAMP Session-Reflector logical 2050 entity"; 2052 leaf admin-state { 2053 type boolean; 2054 default true; 2055 description 2056 "Indicates whether the device is allowed to operate 2057 as a TWAMP Session-Reflector."; 2058 } 2060 leaf refwait { 2061 type uint32 { 2062 range 1..604800; 2063 } 2064 units seconds; 2065 default 900; 2066 description 2067 "The Session-Reflector MAY discontinue any session that 2068 has been started when no packet associated with that 2069 session has been received for REFWAIT seconds. As per 2070 Section 3.1 of RFC 5357, this timeout allows a 2071 Session-Reflector to free up resources in case of 2072 failure."; 2073 } 2075 list test-session { 2076 key 2077 "sender-ip sender-udp-port 2078 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 } 2128 leaf parent-connection-client-ip { 2129 type inet:ip-address; 2130 description 2131 "The IP address on the Control-Client device, which 2132 is the source IP address used in the TWAMP-Control 2133 (TCP) packets belonging to the parent control 2134 connection that negotiated this test session."; 2135 } 2137 leaf parent-connection-client-tcp-port { 2138 type inet:port-number; 2139 description 2140 "The source TCP port number used in the TWAMP-Control 2141 (TCP) packets belonging to the parent control 2142 connection that negotiated this test session."; 2143 } 2145 leaf parent-connection-server-ip { 2146 type inet:ip-address; 2147 description 2148 "The IP address of the Server device, which is the 2149 destination IP address used in the TWAMP-Control 2150 (TCP) packets belonging to the parent control 2151 connection that negotiated this test session."; 2152 } 2154 leaf parent-connection-server-tcp-port { 2155 type inet:port-number; 2156 description 2157 "The destination TCP port number used in the 2158 TWAMP-Control (TCP) packets belonging to the parent 2159 control connection that negotiated this test 2160 session."; 2161 } 2163 leaf test-packet-dscp { 2164 type inet:dscp; 2165 description 2166 "The DSCP value present in the IP header of 2167 TWAMP-Test (UDP) packets belonging to this session."; 2168 } 2170 uses maintenance-statistics; 2171 } 2172 } 2173 } 2174 } 2175 2177 6. Data Model Examples 2179 This section presents a simple but complete example of configuring 2180 all four entities in Figure 1, based on the YANG module specified in 2181 Section 5. The example is illustrative in nature, but aims to be 2182 self-contained, i.e. were it to be executed in a real TWAMP 2183 implementation it would lead to a correctly configured test session. 2184 For completeness, examples are provided for both IPv4 and IPv6. 2186 A more elaborated example, which also includes authentication 2187 parameters, is provided in Appendix A. 2189 6.1. Control-Client 2191 Figure 8 shows a configuration example for a Control-Client with 2192 client/admin-state enabled. In a real implementation following 2193 Figure 2 this would permit the initiation of TWAMP-Control 2194 connections and TWAMP-Test sessions. 2196 [note: '\' line wrapping is for formatting only] 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 [note: '\' line wrapping is for formatting only] 2218 2219 2220 2221 2222 true 2223 2224 RouterA 2225 203.0.113.1 2226 203.0.113.2 2227 2228 Test1 2229 203.0.113.3 2230 54001 2231 203.0.113.4 2232 50001 2233 0 2234 2235 2236 Test2 2237 203.0.113.1 2238 54001 2239 203.0.113.2 2240 50001 2241 0 2242 2243 2244 2245 RouterB 2246 203.0.113.1 2247 203.0.113.3 2248 2249 2250 2251 2253 [note: '\' line wrapping is for formatting only] 2255 2256 2257 2258 2259 true 2260 2261 RouterA 2262 2001:DB8:203:0:113::1 2263 2001:DB8:203:0:113::2 2264 2265 Test1 2266 2001:DB8:203:1:113::3 2267 54000 2268 2001:DB8:203:1:113::4 2269 55000 2270 0 2271 2272 2273 Test2 2274 2001:DB8:203:0:113::1 2275 54001 2276 2001:DB8:203:0:113::2 2277 55001 2278 0 2279 2280 2281 2282 RouterB 2283 2001:DB8:203:0:113::1 2284 2001:DB8:203:0:113::3 2285 2286 2287 2288 2290 6.2. Server 2292 Figure 9 shows a configuration example for a Server with server/ 2293 admin-state enabled, which permits a device following Figure 2 to 2294 respond to TWAMP-Control connections and TWAMP-Test sessions. 2296 [note: '\' line wrapping is for formatting only] 2298 2299 2300 2301 2302 true 2303 2304 2305 2307 Figure 9: XML instance enabling Server operation. 2309 The following example presents a Server with the TWAMP-Control 2310 connection corresponding to the control connection name (client/ctrl- 2311 connection/name) "RouterA" presented in Section 6.1. 2313 [note: '\' line wrapping is for formatting only] 2315 2316 2317 2318 2319 true 2320 2321 203.0.113.1 2322 16341 2323 203.0.113.2 2324 862 2325 active 2326 2327 2328 2329 2331 [note: '\' line wrapping is for formatting only] 2333 2334 2335 2336 2337 true 2338 2339 2001:DB8:203:0:113::1 2340 16341 2341 2001:DB8:203:0:113::2 2342 862 2343 active 2344 2345 2346 2347 2349 6.3. Session-Sender 2351 Figure 10 shows a configuration example for a Session-Sender with 2352 session-sender/admin-state enabled, which permits a device following 2353 Figure 2 to initiate TWAMP-Test sessions. 2355 [note: '\' line wrapping is for formatting only] 2357 2358 2359 2360 2361 true 2362 2363 2364 2366 Figure 10: XML instance enabling Session-Sender operation. 2368 The following configuration example shows a Session-Sender with the 2369 two TWAMP-Test sessions presented in Section 6.1. 2371 [note: '\' line wrapping is for formatting only] 2373 2374 2375 2376 2377 true 2378 2379 Test1 2380 RouterA 2381 900 2382 1 2383 2384 2385 Test2 2386 RouterA 2387 900 2388 1 2389 2 2390 2391 2392 2393 2395 6.4. Session-Reflector 2397 This configuration example shows a Session-Reflector with session- 2398 reflector/admin-state enabled, which permits a device following 2399 Figure 2 to respond to TWAMP-Test sessions. 2401 [note: '\' line wrapping is for formatting only] 2403 2404 2405 2406 2407 true 2408 2409 2410 2412 Figure 11: XML instance enabling Session-Reflector operation. 2414 The following example shows the two Session-Reflector TWAMP-Test 2415 sessions corresponding to the test sessions presented in Section 6.3. 2417 [note: '\' line wrapping is for formatting only] 2419 2420 2421 2422 2423 true 2424 2425 203.0.113.3 2426 54000 2427 203.0.113.4 2428 50001 2429 1232 2430 203.0.113.1 2432 16341 2434 203.0.113.2 2436 862 2438 2 2439 2 2440 1 2441 1 2442 2443 2444 203.0.113.1 2445 54001 2446 192.68.0.2 2447 50001 2448 178943 2449 203.0.113.1 2451 16341 2453 203.0.113.2 2455 862 2457 21 2458 21 2459 20 2460 20 2461 2462 2463 2464 2466 [note: '\' line wrapping is for formatting only] 2468 2469 2470 2471 2472 true 2473 2474 203.0.113.3 2475 54000 2476 203.0.113.4 2477 54001 2478 1232 2479 203.0.113.1 2481 16341 2483 203.0.113.2 2485 862 2487 2 2488 2 2489 1 2490 1 2491 2492 2493 203.0.113.1 2494 54001 2495 192.68.0.2 2496 55001 2497 178943 2498 203.0.113.1 2500 16341 2502 203.0.113.2 2504 862 2506 21 2507 21 2508 20 2509 20 2510 2511 2512 2513 2515 7. Security Considerations 2517 The YANG module specified in Section 5 this document defines a schema 2518 for data that is designed to be accessed via network management 2519 protocols such as NETCONF [RFC6241] or RESTCONF [RFC8040]. The 2520 lowest NETCONF [RFC6241] layer is the secure transport layer, and the 2521 mandatory-to-implement secure transport is Secure Shell (SSH) 2522 [RFC6242]. The lowest RESTCONF layer is HTTPS, and the mandatory-to- 2523 implement secure transport is TLS [RFC5246]. 2525 The NETCONF Access Control Module (NACM) [RFC8341] provides the means 2526 to restrict access for particular NETCONF or RESTCONF users to a 2527 preconfigured subset of all available NETCONF or RESTCONF protocol 2528 operations and content.. 2530 There are a number of nodes defined in this YANG module which are 2531 writeable. These data nodes may be considered sensitive and 2532 vulnerable to attacks in some network environments. Ability to write 2533 into these nodes without proper protection can have a negative effect 2534 on the devices that support this feature. 2536 Examples of nodes that are particularly vulnerable include several 2537 timeout values put in the protocol to protect against sessions that 2538 are not active but are consuming resources. 2540 8. IANA Considerations 2542 This document registers a URI in the IETF XML registry [RFC3688]. 2543 Following the format in IETF XML Registry [RFC3688], the following 2544 registration is requested to be made. 2546 URI: urn:ietf:params:xml:ns:yang:ietf-twamp 2548 Registrant Contact: The IPPM WG of the IETF. 2550 XML: N/A, the requested URI is an XML namespace. 2552 This document registers a YANG module in the YANG Module Names 2553 registry YANG [RFC6020]. 2555 name: ietf-twamp 2557 namespace: urn:ietf:params:xml:ns:yang:ietf-twamp 2559 prefix: twamp 2561 reference: RFC XXXX 2563 9. Acknowledgements 2565 We thank Fred Baker, Kevin D'Souza, Gregory Mirsky, Brian Trammell, 2566 Robert Sherman, and Marius Georgescu for their thorough and 2567 constructive reviews, comments and text suggestions. 2569 Haoxing Shen contributed to the definition of the YANG module in 2570 Section 5. 2572 Jan Lindblad and Ladislav Lhokta did thorough reviews of the YANG 2573 module and the examples in Appendix A. 2575 Kostas Pentikousis was partially supported by FP7 UNIFY 2576 (http://fp7-unify.eu), a research project partially funded by the 2577 European Community under the Seventh Framework Program (grant 2578 agreement no. 619609). The views expressed here are those of the 2579 authors only. The European Commission is not liable for any use that 2580 may be made of the information in this document. 2582 10. Contributors 2584 Lianshu Zheng. 2586 11. References 2588 11.1. Normative References 2590 [I-D.ietf-ippm-port-twamp-test] 2591 Morton, A. and G. Mirsky, "OWAMP and TWAMP Well-Known Port 2592 Assignments", draft-ietf-ippm-port-twamp-test-01 (work in 2593 progress), March 2018. 2595 [RFC1305] Mills, D., "Network Time Protocol (Version 3) 2596 Specification, Implementation and Analysis", RFC 1305, 2597 DOI 10.17487/RFC1305, March 1992, 2598 . 2600 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2601 Requirement Levels", BCP 14, RFC 2119, 2602 DOI 10.17487/RFC2119, March 1997, 2603 . 2605 [RFC3432] Raisanen, V., Grotefeld, G., and A. Morton, "Network 2606 performance measurement with periodic streams", RFC 3432, 2607 DOI 10.17487/RFC3432, November 2002, 2608 . 2610 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2611 DOI 10.17487/RFC3688, January 2004, 2612 . 2614 [RFC4656] Shalunov, S., Teitelbaum, B., Karp, A., Boote, J., and M. 2615 Zekauskas, "A One-way Active Measurement Protocol 2616 (OWAMP)", RFC 4656, DOI 10.17487/RFC4656, September 2006, 2617 . 2619 [RFC5357] Hedayat, K., Krzanowski, R., Morton, A., Yum, K., and J. 2620 Babiarz, "A Two-Way Active Measurement Protocol (TWAMP)", 2621 RFC 5357, DOI 10.17487/RFC5357, October 2008, 2622 . 2624 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2625 the Network Configuration Protocol (NETCONF)", RFC 6020, 2626 DOI 10.17487/RFC6020, October 2010, 2627 . 2629 [RFC6038] Morton, A. and L. Ciavattone, "Two-Way Active Measurement 2630 Protocol (TWAMP) Reflect Octets and Symmetrical Size 2631 Features", RFC 6038, DOI 10.17487/RFC6038, October 2010, 2632 . 2634 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 2635 RFC 6991, DOI 10.17487/RFC6991, July 2013, 2636 . 2638 [RFC7312] Fabini, J. and A. Morton, "Advanced Stream and Sampling 2639 Framework for IP Performance Metrics (IPPM)", RFC 7312, 2640 DOI 10.17487/RFC7312, August 2014, 2641 . 2643 [RFC7717] Pentikousis, K., Ed., Zhang, E., and Y. Cui, 2644 "IKEv2-Derived Shared Secret Key for the One-Way Active 2645 Measurement Protocol (OWAMP) and Two-Way Active 2646 Measurement Protocol (TWAMP)", RFC 7717, 2647 DOI 10.17487/RFC7717, December 2015, 2648 . 2650 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2651 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2652 . 2654 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2655 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2656 May 2017, . 2658 11.2. Informative References 2660 [I-D.ietf-ippm-metric-registry] 2661 Bagnulo, M., Claise, B., Eardley, P., Morton, A., and A. 2662 Akhter, "Registry for Performance Metrics", draft-ietf- 2663 ippm-metric-registry-14 (work in progress), March 2018. 2665 [I-D.unify-nfvrg-challenges] 2666 Szabo, R., Csaszar, A., Pentikousis, K., Kind, M., Daino, 2667 D., Qiang, Z., and H. Woesner, "Unifying Carrier and Cloud 2668 Networks: Problem Statement and Challenges", draft-unify- 2669 nfvrg-challenges-04 (work in progress), July 2016. 2671 [I-D.unify-nfvrg-devops] 2672 Meirosu, C., Manzalini, A., Steinert, R., Marchetto, G., 2673 Pentikousis, K., Wright, S., Lynch, P., and W. John, 2674 "DevOps for Software-Defined Telecom Infrastructures", 2675 draft-unify-nfvrg-devops-06 (work in progress), July 2016. 2677 [NSC] John, W., Pentikousis, K., et al., "Research directions in 2678 network service chaining", Proc. SDN for Future Networks 2679 and Services (SDN4FNS), Trento, Italy IEEE, November 2013. 2681 [RFC4086] Eastlake 3rd, D., Schiller, J., and S. Crocker, 2682 "Randomness Requirements for Security", BCP 106, RFC 4086, 2683 DOI 10.17487/RFC4086, June 2005, 2684 . 2686 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2687 (TLS) Protocol Version 1.2", RFC 5246, 2688 DOI 10.17487/RFC5246, August 2008, 2689 . 2691 [RFC5618] Morton, A. and K. Hedayat, "Mixed Security Mode for the 2692 Two-Way Active Measurement Protocol (TWAMP)", RFC 5618, 2693 DOI 10.17487/RFC5618, August 2009, 2694 . 2696 [RFC5938] Morton, A. and M. Chiba, "Individual Session Control 2697 Feature for the Two-Way Active Measurement Protocol 2698 (TWAMP)", RFC 5938, DOI 10.17487/RFC5938, August 2010, 2699 . 2701 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2702 and A. Bierman, Ed., "Network Configuration Protocol 2703 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2704 . 2706 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 2707 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 2708 . 2710 [RFC7426] Haleplidis, E., Ed., Pentikousis, K., Ed., Denazis, S., 2711 Hadi Salim, J., Meyer, D., and O. Koufopavlou, "Software- 2712 Defined Networking (SDN): Layers and Architecture 2713 Terminology", RFC 7426, DOI 10.17487/RFC7426, January 2714 2015, . 2716 [RFC8018] Moriarty, K., Ed., Kaliski, B., and A. Rusch, "PKCS #5: 2717 Password-Based Cryptography Specification Version 2.1", 2718 RFC 8018, DOI 10.17487/RFC8018, January 2017, 2719 . 2721 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2722 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2723 . 2725 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 2726 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 2727 . 2729 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 2730 Access Control Model", STD 91, RFC 8341, 2731 DOI 10.17487/RFC8341, March 2018, 2732 . 2734 Appendix A. Detailed Data Model Examples 2736 This appendix extends the example presented in Section 6 by 2737 configuring more fields such as authentication parameters, DSCP 2738 values and so on. 2740 A.1. Control-Client 2742 [note: '\' line wrapping is for formatting only] 2744 2745 2746 2747 2748 true 2749 2750 0 2751 authenticated 2752 2753 2754 1 2755 unauthenticated 2756 2757 2758 KeyClient1ToRouterA 2759 c2VjcmV0MQ== 2760 2761 2762 KeyForRouterB 2763 c2VjcmV0Mg0K 2764 2765 2766 RouterA 2767 203.0.113.1 2768 203.0.113.2 2769 32 2770 KeyClient1ToRouterA 2771 2772 Test1 2773 203.0.113.3 2774 54000 2775 203.0.113.4 2776 55000 2777 64 2778 0 2779 2780 2781 Test2 2782 203.0.113.1 2783 54001 2784 203.0.113.2 2785 55001 2786 128 2787 0 2788 2789 2790 2791 2792 2794 [note: '\' line wrapping is for formatting only] 2796 2797 2798 2799 2800 true 2801 2802 0 2803 authenticated 2804 2805 2806 1 2807 unauthenticated 2808 2809 2810 KeyClient1ToRouterA 2811 c2VjcmV0MQ== 2812 2813 2814 KeyForRouterB 2815 c2VjcmV0Mg0K 2816 2817 2818 RouterA 2819 2001:DB8:203:0:113::1 2820 2001:DB8:203:0:113::2 2821 32 2822 KeyClient1ToRouterA 2823 2824 Test1 2825 2001:DB8:10:1:1::1 2826 54000 2827 2001:DB8:10:1:1::2 2828 55000 2829 64 2830 0 2831 2832 2833 Test2 2834 2001:DB8:203:0:113::1 2835 54001 2836 2001:DB8:203:0:113::2 2837 55001 2838 128 2839 0 2840 2841 2842 2843 2844 2846 A.2. Server 2848 [note: '\' line wrapping is for formatting only] 2850 2851 2852 2853 2854 true 2855 1800 2856 32 2857 authenticated unauthenticated 2858 30 2859 2860 KeyClient1ToRouterA 2861 c2VjcmV0MQ== 2862 2863 2864 KeyClient10ToRouterA 2865 c2VjcmV0MTANCg== 2866 2867 2868 203.0.113.1 2869 16341 2870 203.0.113.2 2871 862 2872 32 2873 unauthenticated 2874 KeyClient1ToRouterA 2875 30 2876 2877 2878 2879 2881 [note: '\' line wrapping is for formatting only] 2883 2884 2885 2886 2887 true 2888 1800 2889 32 2890 authenticated unauthenticated 2891 30 2892 2893 KeyClient1ToRouterA 2894 c2VjcmV0MQ== 2895 2896 2897 KeyClient10ToRouterA 2898 c2VjcmV0MTANCg== 2899 2900 2901 2001:DB8:203:0:113::1 2902 16341 2903 2001:DB8:203:0:113::2 2904 862 2905 32 2906 unauthenticated 2907 KeyClient1ToRouterA 2908 30 2909 2910 2911 2912 2914 A.3. Session-Sender 2916 [note: '\' line wrapping is for formatting only] 2918 2919 2920 2921 2922 true 2923 2924 Test1 2925 RouterA 2926 zero 2927 900 2928 1 2929 2 2930 2 2931 1 2932 1 2933 2934 2935 Test2 2936 RouterA 2937 random 2938 900 2939 1 2940 2 2941 21 2942 21 2943 20 2944 20 2945 2946 2947 2948 2950 A.4. Session-Reflector 2952 [note: '\' line wrapping is for formatting only] 2954 2955 2956 2957 2958 true 2959 2960 203.0.113.3 2961 54000 2962 203.0.113.4 2963 55000 2964 1232 2965 203.0.113.1 2967 16341 2969 203.0.113.2 2971 862 2973 32 2974 2 2975 2 2976 1 2977 1 2978 2979 2980 203.0.113.1 2981 54001 2982 192.68.0.2 2983 55001 2984 178943 2985 203.0.113.1 2987 16341 2989 203.0.113.2 2991 862 2993 32 2994 21 2995 21 2996 20 2997 20 2998 2999 3000 3001 3003 [note: '\' line wrapping is for formatting only] 3005 3006 3007 3008 3009 true 3010 3011 2001:DB8:10:1:1::1 3012 54000 3013 2001:DB8:10:1:1::2 3014 55000 3015 1232 3016 2001:DB8:203:0:113::1 3018 16341 3020 2001:DB8:203:0:113::2 3022 862 3024 32 3025 2 3026 2 3027 1 3028 1 3029 3030 3031 2001:DB8:203:0:113::1 3032 54001 3033 2001:DB8:192:68::2 3034 55001 3035 178943 3036 2001:DB8:203:0:113::1 3038 16341 3040 2001:DB8:203:0:113::2 3042 862 3044 32 3045 21 3046 21 3047 20 3048 20 3049 3050 3051 3052 3054 Appendix B. TWAMP Operational Commands 3056 TWAMP operational commands could be performed programmatically or 3057 manually, e.g. using a command-line interface (CLI). 3059 With respect to programmability, YANG can be used to define NETCONF 3060 Remote Procedure Calls (RPC), therefore it would be, in principle, 3061 possible to define TWAMP RPC operations for actions such as starting 3062 or stopping control connections or test sessions or groups of 3063 sessions; retrieving results; clearing stored results, and so on. 3065 However, TWAMP [RFC5357] does not attempt to describe such 3066 operational actions. Refer also to Section 2 and the unlabeled links 3067 in Figure 1. In actual deployments different TWAMP implementations 3068 may support different sets of operational commands, with different 3069 restrictions. Therefore, this document considers it the 3070 responsibility of the individual implementation to define its 3071 corresponding TWAMP operational commands data model. 3073 Authors' Addresses 3075 Ruth Civil 3076 Ciena Corporation 3077 307 Legget Drive 3078 Kanata, ON K2K 3C8 3079 Canada 3081 Email: gcivil@ciena.com 3082 URI: www.ciena.com 3084 Al Morton 3085 AT&T Labs 3086 200 Laurel Avenue South 3087 Middletown,, NJ 07748 3088 USA 3090 Phone: +1 732 420 1571 3091 Fax: +1 732 368 1192 3092 Email: acmorton@att.com 3093 Reshad Rahman 3094 Cisco Systems 3095 2000 Innovation Drive 3096 Kanata, ON K2K 3E8 3097 Canada 3099 Email: rrahman@cisco.com 3101 Mahesh Jethanandani 3103 Email: mjethanandani@gmail.com 3105 Kostas Pentikousis (editor) 3106 Travelping 3107 Siemensdamm 50 3108 Berlin 13629 3109 Germany 3111 Email: k.pentikousis@travelping.com