idnits 2.17.1 draft-ietf-ippm-twamp-yang-11.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 (May 25, 2018) is 2155 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-24) exists of draft-ietf-ippm-metric-registry-14 == Outdated reference: A later version (-04) exists of draft-ietf-ippm-port-twamp-test-01 -- Obsolete informational reference (is this intentional?): RFC 5246 (Obsoleted by RFC 8446) Summary: 0 errors (**), 0 flaws (~~), 5 warnings (==), 2 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: November 26, 2018 AT&T Labs 6 R. Rahman 7 Cisco Systems 8 M. Jethanandani 10 K. Pentikousis, Ed. 11 Travelping 12 May 25, 2018 14 Two-Way Active Measurement Protocol (TWAMP) Data Model 15 draft-ietf-ippm-twamp-yang-11 17 Abstract 19 This document specifies a data model for client and server 20 implementations of the Two-Way Active Measurement Protocol (TWAMP). 21 The document defines the TWAMP data model through Unified Modeling 22 Language (UML) class diagrams and formally specifies it using 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 November 26, 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 . . . . . . . . . . . . . . . . . . . . . 64 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 1.1 [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], and 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, it is expected 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 1.1 [RFC7950] data modeling 132 language. 134 Note to RFC Editor: 136 Please replace the date 2018-05-25 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-ippm-port-twamp-test with the 139 RFC 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 the TWAMP data model is described in the remaining sections of 246 this document, readers should keep in mind the functional entity 247 grouping 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, the following 278 configuration items should be noted: 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 integers 408 increase by one. 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, a sequence 432 of octets of arbitrary length whose interpretation is unspecified. 433 The key-id and secret-key encoding SHOULD follow Section 9.4 of YANG 434 [RFC7950]. The derived key length (dkLen in PKCS #5: Password-Based 435 Cryptography Specification Version 2.1 [RFC8018]) MUST be 16 octets 436 for the AES Session-key used for encryption and 32 octets for the 437 HMAC-SHA1 Session-key used for authentication; see also Section 6.10 438 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? binary 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-exponent? 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-exponent? uint8 719 | +--rw modes? twamp-modes 720 | +--rw key-chain* [key-id] 721 | | +--rw key-id string 722 | | +--rw secret-key? binary 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-exponent? 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 Common 787 YANG Data Types [RFC6991], and references NTPv3 Specification 788 [RFC5905], Framework for IP Performance Metrics [RFC2330], Randomness 789 Requirements for Security [RFC4086], OWAMP [RFC4656], TWAMP 790 [RFC5357], More Features for TWAMP [RFC5618], Individual Session 791 Control Feature [RFC5938], TWAMP Reflect Octets and Symmetrical Size 792 Features [RFC6038], Advances Stream and Sampling Framework [RFC7312], 793 IKEv2-Derived Shared Secret Key for OWAMP and TWAMP [RFC7717], and 794 OWAMP and TWAMP Well-Known Port Assignments 795 [I-D.ietf-ippm-port-twamp-test]. 797 file "ietf-twamp@2018-05-25.yang" 799 module ietf-twamp { 800 yang-version 1.1; 801 namespace urn:ietf:params:xml:ns:yang:ietf-twamp; 802 prefix ietf-twamp; 804 import ietf-inet-types { 805 prefix inet; 806 reference 807 "RFC 6991: Common YANG Types."; 808 } 810 organization 811 "IETF IPPM (IP Performance Metrics) Working Group"; 813 contact 814 "WG Web: http://tools.ietf.org/wg/ippm/ 815 WG List: ippm@ietf.org 817 Editor: Ruth Civil 818 gcivil@ciena.com 819 Editor: Al Morton 820 acmorton@att.com 821 Editor: Reshad Rehman 822 rrahman@cisco.com 823 Editor: Mahesh Jethanandani 824 mjethanandani@gmail.com 825 Editor: Kostas Pentikousis 826 k.pentikousis@travelping.com"; 828 description 829 "This YANG module specifies a vendor-independent data 830 model for the Two-Way Active Measurement Protocol (TWAMP). 832 The data model covers four TWAMP logical entities, namely, 833 Control-Client, Server, Session-Sender, and Session-Reflector, 834 as illustrated in the annotated TWAMP logical model (Fig. 1 835 of RFC XXXX). 837 This YANG module uses features to indicate which of the four 838 logical entities are supported by a TWAMP implementation. 840 Copyright (c) 2018 IETF Trust and the persons identified as 841 the document authors. All rights reserved. 842 Redistribution and use in source and binary forms, with or 843 without modification, is permitted pursuant to, and subject 844 to the license terms contained in, the Simplified BSD 845 License set forth in Section 4.c of the IETF Trust's Legal 846 Provisions Relating to IETF Documents 847 (http://trustee.ietf.org/license-info). 849 This version of this YANG module is part of RFC XXXX; see 850 the RFC itself for full legal notices."; 852 revision 2018-05-25 { 853 description 854 "Initial Revision. 856 Covers RFC 5357, RFC 5618, RFC 5938, RFC 6038, RFC 7717, and 857 draft-ietf-ippm-metric-registry"; 859 reference 860 "RFC XXXX: TWAMP YANG Data Model."; 861 } 863 /* 864 * Typedefs 865 */ 867 typedef twamp-modes { 868 type bits { 869 bit unauthenticated { 870 position 0; 871 description 872 "Unauthenticated mode, in which no encryption or 873 authentication is applied in TWAMP-Control and 874 TWAMP-Test. KeyID, Token, and Client-IV are not used in 875 the Set-Up-Response message. See Section 3.1 of 876 RFC 4656."; 878 reference 879 "RFC 4656: A One-way Active Measurement Protocol 880 (OWAMP)"; 881 } 882 bit authenticated { 883 position 1; 884 description 885 "Authenticated mode, in which the Control-Client and 886 Server possess a shared secret thus prohibiting 887 'theft of service'. As per Section 6 of RFC 4656, 888 in 'authenticated mode, the timestamp is in the clear 889 and is not protected cryptographically in any way, 890 while the rest of the message has the same protection 891 as in encrypted mode. This mode allows one to trade off 892 cryptographic protection against accuracy of 893 timestamps.'"; 894 reference 895 "RFC 4656: A One-way Active Measurement Protocol 896 (OWAMP)"; 897 } 898 bit encrypted { 899 position 2; 900 description 901 "Encrypted mode 'makes it impossible to alter 902 timestamps undetectably.' See also Section 4 of RFC 7717 903 and Section 6 of RFC 4656."; 904 reference 905 "RFC 4656: A One-way Active Measurement Protocol 906 (OWAMP)"; 907 } 908 bit unauth-test-encrpyt-control { 909 position 3; 910 description 911 "When using the Mixed Security Mode, the TWAMP-Test 912 protocol follows the Unauthenticated mode and the 913 TWAMP-Control protocol the Encrypted mode."; 914 reference 915 "RFC 5618: Mixed Security Mode for the Two-Way Active 916 Measurement Protocol (TWAMP)"; 917 } 918 bit individual-session-control { 919 position 4; 920 description 921 "This mode enables individual test sessions using 922 Session Identifiers."; 923 reference 924 "RFC 5938: Individual Session Control Feature 925 for the Two-Way Active Measurement Protocol (TWAMP)"; 927 } 928 bit reflect-octets { 929 position 5; 930 description 931 "This mode indicates the reflect octets capability."; 932 reference 933 "RFC 6038: Two-Way Active Measurement Protocol (TWAMP) 934 Reflect Octets and Symmetrical Size Features"; 935 } 936 bit symmetrical-size { 937 position 6; 938 description 939 "This mode indicates support for the symmetrical size 940 sender test packet format."; 941 reference 942 "RFC 6038: Two-Way Active Measurement Protocol (TWAMP) 943 Reflect Octets and Symmetrical Size Features"; 944 } 945 bit IKEv2Derived { 946 position 7; 947 description 948 "In this mode the the shared key is derived 949 from an IKEv2 security association (SA)."; 950 reference 951 "RFC 7717: IKEv2-Derived Shared Secret Key for 952 the One-Way Active Measurement Protocol (OWAMP) 953 and Two-Way Active Measurement Protocol (TWAMP)"; 954 } 955 } 956 description 957 "Specifies the configurable TWAMP-Modes supported during a 958 TWAMP-Control Connection setup between a Control-Client 959 and a Server. Section 7 of RFC 7717 summarizes the 960 TWAMP-Modes registry and points to their formal 961 specification."; 962 } 964 typedef control-client-connection-state { 965 type enumeration { 966 enum active { 967 description 968 "Indicates an active TWAMP-Control connection to 969 Server."; 970 } 971 enum idle { 972 description 973 "Indicates an idle TWAMP-Control connection to Server."; 974 } 976 } 977 description 978 "Indicates the Control-Client TWAMP-Control connection 979 state."; 980 } 982 typedef test-session-state { 983 type enumeration { 984 enum accepted { 985 value 0; 986 description 987 "Indicates an accepted TWAMP-Test session request."; 988 } 989 enum failed { 990 value 1; 991 description 992 "Indicates a TWAMP-Test session failure due to 993 some unspecified reason (catch-all)."; 994 } 995 enum internal-error { 996 value 2; 997 description 998 "Indicates a TWAMP-Test session failure due to 999 an internal error."; 1000 } 1001 enum not-supported { 1002 value 3; 1003 description 1004 "Indicates a TWAMP-Test session failure because 1005 some aspect of the TWAMP-Test session request 1006 is not supported."; 1007 } 1008 enum permanent-resource-limit { 1009 value 4; 1010 description 1011 "Indicates a TWAMP-Test session failure due to 1012 permanent resource limitations."; 1013 } 1014 enum temp-resource-limit { 1015 value 5; 1016 description 1017 "Indicates a TWAMP-Test session failure due to 1018 temporary resource limitations."; 1019 } 1020 } 1021 description 1022 "Indicates the Control-Client TWAMP-Test session state."; 1023 } 1024 typedef server-ctrl-connection-state { 1025 type enumeration { 1026 enum active { 1027 description 1028 "Indicates an active TWAMP-Control connection 1029 to the Control-Client."; 1030 } 1031 enum servwait { 1032 description 1033 "Indicates that the TWAMP-Control connection to the 1034 Control-Client is in SERVWAIT as per the definition of 1035 Section 3.1 of RFC 5357."; 1036 } 1037 } 1038 description 1039 "Indicates the Server TWAMP-Control connection state."; 1040 } 1042 typedef sender-session-state { 1043 type enumeration { 1044 enum active { 1045 description 1046 "Indicates that the TWAMP-Test session is active."; 1047 } 1048 enum failure { 1049 description 1050 "Indicates that the TWAMP-Test session has failed."; 1051 } 1052 } 1053 description 1054 "Indicates the Session-Sender TWAMP-Test session state."; 1055 } 1057 typedef padding-fill-mode { 1058 type enumeration { 1059 enum zero { 1060 description 1061 "TWAMP-Test packets are padded with all zeros."; 1062 } 1063 enum random { 1064 description 1065 "TWAMP-Test packets are padded with pseudo-random 1066 numbers."; 1067 } 1068 } 1069 description 1070 "Indicates what type of packet padding is used in the 1071 TWAMP-Test packets."; 1073 } 1075 typedef dynamic-port-number { 1076 type inet:port-number { 1077 range 49152..65535; 1078 } 1079 description "Dynamic range for port numbers."; 1080 } 1082 /* 1083 * Features 1084 */ 1086 feature control-client { 1087 description 1088 "Indicates that the device supports configuration of the 1089 TWAMP Control-Client logical entity."; 1090 } 1092 feature server { 1093 description 1094 "Indicates that the device supports configuration of the 1095 TWAMP Server logical entity."; 1096 } 1098 feature session-sender { 1099 description 1100 "Indicates that the device supports configuration of the 1101 TWAMP Session-Sender logical entity."; 1102 } 1104 feature session-reflector { 1105 description 1106 "Indicates that the device supports configuration of the 1107 TWAMP Session-Reflector logical entity."; 1108 } 1110 /* 1111 * Reusable node groups 1112 */ 1114 grouping key-management { 1115 list key-chain { 1116 key key-id; 1117 leaf key-id { 1118 type string { 1119 length 1..80; 1121 } 1122 description 1123 "KeyID used for a TWAMP-Control connection. As per 1124 Section 3.1 of RFC 4656, KeyID is 'a UTF-8 string, up to 1125 80 octets in length' and is used to select which 'shared 1126 shared secret the [Control-Client] wishes to use to 1127 authenticate or encrypt'."; 1128 } 1129 leaf secret-key { 1130 type binary; 1131 description 1132 "The secret key corresponding to the KeyID for this 1133 TWAMP-Control connection."; 1134 } 1135 description 1136 "Relates KeyIDs with their respective secret keys 1137 in a TWAMP-Control connection."; 1138 } 1139 description 1140 "Used by the Control-Client and Server for TWAMP-Control 1141 key management."; 1142 } 1144 grouping maintenance-statistics { 1145 leaf sent-packets { 1146 type uint32; 1147 config false; 1148 description 1149 "Indicates the number of packets sent."; 1150 } 1152 leaf rcv-packets { 1153 type uint32; 1154 config false; 1155 description 1156 "Indicates the number of packets received."; 1157 } 1159 leaf last-sent-seq { 1160 type uint32; 1161 config false; 1162 description 1163 "Indicates the last sent sequence number."; 1164 } 1166 leaf last-rcv-seq { 1167 type uint32; 1168 config false; 1169 description 1170 "Indicates the last received sequence number."; 1171 } 1172 description 1173 "Used for TWAMP-Test maintenance statistics."; 1174 } 1176 grouping count { 1177 leaf count { 1178 type uint8 { 1179 range "10..31"; 1180 } 1181 default 10; 1182 description 1183 "Parameter communicated to the Control-Client as part of 1184 the Server Greeting message and used for deriving a key 1185 from a shared secret as per Section 3.1 of RFC 4656: 1186 MUST be a power of 2 and at least 1024. It is configured 1187 by providing said power. For example, configuring 15 here 1188 means count 2^15 = 32768. The default is 10, 1189 meaning 2^10 = 1024."; 1190 } 1191 description 1192 "Reusable data structure for count, which is used both in the 1193 Server and the Control-Client."; 1194 } 1196 grouping max-count-exponent { 1197 leaf max-count-exponent { 1198 type uint8 { 1199 range 10..31; 1200 } 1201 default 15; 1202 description 1203 "This parameter limits the maximum Count value, which MUST 1204 be a power of 2 and at least 1024 as per RFC 5357. It is 1205 configured by providing said power. For example, 1206 configuring 10 here means max count 2^10 = 1024. 1207 The default is 15, meaning 2^15 = 32768. 1209 A TWAMP Server uses this configured value in the 1210 Server-Greeting message sent to the Control-Client. 1212 A TWAMP Control-Client uses this configured value to 1213 prevent denial-of-service (DOS) attacks by closing the 1214 control connection to the Server if it 'receives a 1215 Server-Greeting message with Count greater that its 1216 maximum configured value', as per Section 6 of RFC 5357. 1218 Further, note that according to Section 6 of RFC 5357: 1220 'If an attacking system sets the maximum value in 1221 Count (2**32), then the system under attack would stall 1222 for a significant period of time while it attempts to 1223 generate keys. 1225 TWAMP-compliant systems SHOULD have a configuration 1226 control to limit the maximum count value. The default 1227 max-count-exponent value SHOULD be 15 which corresponds 1228 to a maximum value of 2**15 or 32768.' 1230 RFC 5357 does not qualify 'significant period' in terms of 1231 time, but it is clear that this depends on the processing 1232 capacity available and operators need to pay attention to 1233 this security consideration."; 1234 } 1235 description 1236 "Reusable data structure for max-count which is used both at 1237 the Control-Client and the Server containers."; 1238 } 1240 /* 1241 * Configuration data nodes 1242 */ 1244 container twamp { 1245 description 1246 "TWAMP logical entity configuration grouping of four models 1247 which correspond to the four TWAMP logical entities 1248 Control-Client, Server, Session-Sender, and Session-Reflector 1249 as illustrated in Fig. 1 of RFC XXXX."; 1251 container client { 1252 if-feature control-client; 1253 description 1254 "Configuration of the TWAMP Control-Client logical 1255 entity."; 1257 leaf admin-state { 1258 type boolean; 1259 default true; 1260 description 1261 "Indicates whether the device is allowed to operate as a 1262 TWAMP Control-Client."; 1263 } 1264 list mode-preference-chain { 1265 key priority; 1266 unique mode; 1267 leaf priority { 1268 type uint16; 1269 description 1270 "Indicates the Control-Client Mode preference priority 1271 expressed as a 16-bit unsigned integer, where zero is 1272 the highest priority and subsequent values 1273 monotonically increasing."; 1274 } 1275 leaf mode { 1276 type twamp-modes; 1277 description 1278 "The supported TWAMP Mode matching the corresponding 1279 priority."; 1281 } 1282 description 1283 "Indicates the Control-Client preferred order of use of 1284 the supported TWAMP Modes. 1286 Depending on the Modes available in the TWAMP Server 1287 Greeting message (see Fig. 2 of RFC 7717), the 1288 this Control-Client MUST choose the highest priority 1289 Mode from the configured mode-preference-chain list."; 1290 } 1292 uses key-management; 1294 list ctrl-connection { 1295 key name; 1296 description 1297 "List of TWAMP Control-Client control connections. 1298 Each item in the list describes a control connection 1299 that will be initiated by this Control-Client"; 1301 leaf name { 1302 type string; 1303 description 1304 "A unique name used as a key to identify this 1305 individual TWAMP-Control connection on the 1306 Control-Client device."; 1307 } 1308 leaf client-ip { 1309 type inet:ip-address; 1310 description 1311 "The IP address of the local Control-Client device, 1312 to be placed in the source IP address field of the 1313 IP header in TWAMP-Control (TCP) packets belonging 1314 to this control connection. If not configured, the 1315 device SHALL choose its own source IP address."; 1316 } 1317 leaf server-ip { 1318 type inet:ip-address; 1319 mandatory true; 1320 description 1321 "The IP address of the remote Server device, which the 1322 TWAMP-Control connection will be initiated to."; 1323 } 1325 leaf server-tcp-port { 1326 type inet:port-number; 1327 default 862; 1328 description 1329 "This parameter defines the TCP port number that is 1330 to be used by this outgoing TWAMP-Control connection. 1331 Typically, this is the well-known TWAMP-Control 1332 port number (862) as per RFC 5357 However, there are 1333 known realizations of TWAMP in the field that were 1334 implemented before this well-known port number was 1335 allocated. These early implementations allowed the 1336 port number to be configured. This parameter is 1337 therefore provided for backward compatibility 1338 reasons."; 1339 } 1341 leaf control-packet-dscp { 1342 type inet:dscp; 1343 default 0; 1344 description 1345 "The DSCP value to be placed in the IP header of 1346 TWAMP-Control (TCP) packets generated by this 1347 Control-Client."; 1348 } 1350 leaf key-id { 1351 type string { 1352 length 1..80; 1353 } 1354 description 1355 "Indicates the KeyID value selected for this 1356 TWAMP-Control connection."; 1357 } 1359 uses max-count-exponent; 1360 leaf client-tcp-port { 1361 type inet:port-number; 1362 config false; 1363 description 1364 "Indicates the source TCP port number used in the 1365 TWAMP-Control packets belonging to this control 1366 connection."; 1367 } 1369 leaf server-start-time { 1370 type uint64; 1371 config false; 1372 description 1373 "Indicates the Start-Time advertized by the Server in 1374 the Server-Start message (RFC 4656, Section 3.1), 1375 representing the time when the current 1376 instantiation of the Server started operating. 1377 The timestamp format follows RFC 1305 1378 according to Section 4.1.2 of RFC 4656."; 1379 reference 1380 "RFC 4656: OWAMP, Section 3.1 and 4.1.2, 1381 RFC 1305: NTPv3 Specification."; 1382 } 1384 leaf repeat-count { 1385 type uint64; 1386 config false; 1387 description 1388 "Indicates how many times the test session has been 1389 repeated. When a test is running, this value will be 1390 greater than 0. If the repeat parameter is non-zero, 1391 this value is smaller than or equal to the repeat 1392 parameter."; 1393 } 1394 leaf state { 1395 type control-client-connection-state; 1396 config false; 1397 description 1398 "Indicates the current state of the TWAMP-Control 1399 connection state."; 1400 } 1402 leaf selected-mode { 1403 type twamp-modes; 1404 config false; 1405 description 1406 "The TWAMP Mode that the Control-Client has chosen for 1407 this control connection as set in the Mode field of 1408 the Set-Up-Response message"; 1409 reference 1410 "RFC 4656, Section 3.1."; 1411 } 1413 leaf token { 1414 type binary { 1415 length 64; 1416 } 1417 config false; 1418 description 1419 "This parameter holds the 64 octets containing the 1420 concatenation of a 16-octet Challenge, a 16-octet AES 1421 Session-key used for encryption, and a 32-octet 1422 HMAC-SHA1 Session-key used for authentication; see 1423 also the last paragraph of Section 6 in RFC 4656. 1425 If the Mode defined in RFC 7717 is selected 1426 (selected-mode), Token is limited to 16 octets."; 1427 reference 1428 "RFC 4086: Randomness Requirements for Security 1430 RFC 7717: IKEv2-Derived Shared Secret Key for the 1431 One-Way Active Measurement Protocol (OWAMP) and 1432 Two-Way Active Measurement Protocol (TWAMP)"; 1433 } 1435 leaf client-iv { 1436 type binary { 1437 length 16; 1438 } 1439 config false; 1440 description 1441 "Indicates the Control-Client Initialization Vector 1442 (Client-IV), that is generated randomly by the 1443 Control-Client. As per RFC 4656: 1445 Client-IV merely needs to be unique (i.e., it MUST 1446 never be repeated for different sessions using the 1447 same secret key; a simple way to achieve that without 1448 the use of cumbersome state is to generate the 1449 Client-IV values using a cryptographically secure 1450 pseudo-random number source. 1452 If the Mode defined in RFC 7717 is selected 1453 (selected-mode), Client-IV is limited to 12 octets."; 1454 reference 1455 "RFC 4656: A One-way Active Measurement Protocol 1456 (OWAMP). 1458 RFC 7717: IKEv2-Derived Shared Secret Key for the 1459 One-Way Active Measurement Protocol (OWAMP) and 1460 Two-Way Active Measurement Protocol (TWAMP)"; 1461 } 1463 list test-session-request { 1464 key name; 1465 description 1466 "Information associated with the Control-Client 1467 for this test session"; 1469 leaf name { 1470 type string; 1471 description 1472 "A unique name to be used for identification of 1473 this TWAMP-Test session on the Control-Client."; 1474 } 1476 leaf sender-ip { 1477 type inet:ip-address; 1478 description 1479 "The IP address of the Session-Sender device, 1480 which is to be placed in the source IP address 1481 field of the IP header in TWAMP-Test (UDP) packets 1482 belonging to this test session. This value will be 1483 used to populate the sender address field of the 1484 Request-TW-Session message. 1486 If not configured, the device SHALL choose its own 1487 source IP address."; 1488 } 1490 leaf sender-udp-port { 1491 type union { 1492 type dynamic-port-number; 1493 type enumeration { 1494 enum autoallocate { 1495 description 1496 "Indicates that the Contol-Client will 1497 auto-allocate the TWAMP-Test (UDP) port number 1498 from the dynamic port range."; 1499 } 1500 } 1501 } 1502 default autoallocate; 1503 description 1504 "The UDP port number that is to be used by 1505 the Session-Sender for this TWAMP-Test session. 1506 The number is restricted to the dynamic port range. 1508 By default the Control-Client SHALL auto-allocate a 1509 UDP port number for this TWAMP-Test session. 1511 The configured (or auto-allocated) value is 1512 advertized in the Sender Port field of the 1513 Request-TW-session message (see Section 3.5 of 1514 RFC 5357). Note that in the scenario where a device 1515 auto-allocates a UDP port number for a session, and 1516 the repeat parameter for that session indicates that 1517 it should be repeated, the device is free to 1518 auto-allocate a different UDP port number when it 1519 negotiates the next (repeated) iteration of this 1520 session."; 1521 } 1523 leaf reflector-ip { 1524 type inet:ip-address; 1525 mandatory true; 1526 description 1527 "The IP address belonging to the remote 1528 Session-Reflector device to which the TWAMP-Test 1529 session will be initiated. This value will be 1530 used to populate the receiver address field of 1531 the Request-TW-Session message."; 1532 } 1534 leaf reflector-udp-port { 1535 type inet:port-number { 1536 range "862 | 49152..65535"; 1537 } 1538 description 1539 "This parameter defines the UDP port number that 1540 will be used by the Session-Reflector for 1541 this TWAMP-Test session. The default number is 1542 within the dynamic port range and is to be placed 1543 in the Receiver Port field of the Request-TW-Session 1544 message. The well-known port (862) MAY be 1545 used."; 1546 reference 1547 "draft-ietf-ippm-port-twamp-test: OWAMP and TWAMP 1548 Well-Known Port Assignments."; 1549 } 1551 leaf timeout { 1552 type uint64; 1553 units seconds; 1554 default 2; 1555 description 1556 "The length of time (in seconds) that the 1557 Session-Reflector should continue to respond to 1558 packets belonging to this TWAMP-Test session after 1559 a Stop-Sessions TWAMP-Control message has been 1560 received. 1562 This value will be placed in the Timeout field of 1563 the Request-TW-Session message."; 1564 reference 1565 "RFC 5357: TWAMP, Section 3.8"; 1566 } 1568 leaf padding-length { 1569 type uint32 { 1570 range 64..4096; 1571 } 1572 description 1573 "The number of padding bytes to be added to the 1574 TWAMP-Test (UDP) packets generated by the 1575 Session-Sender. 1577 This value will be placed in the Padding Length 1578 field of the Request-TW-Session message."; 1579 reference 1580 "RFC 4656, Section 3.5."; 1581 } 1583 leaf test-packet-dscp { 1584 type inet:dscp; 1585 default 0; 1586 description 1587 "The DSCP value to be placed in the IP header 1588 of TWAMP-Test packets generated by the 1589 Session-Sender, and in the UDP header of the 1590 TWAMP-Test response packets generated by the 1591 Session-Reflector for this test session. 1593 This value will be placed in the Type-P Descriptor 1594 field of the Request-TW-Session message"; 1595 reference 1596 "RFC 5357."; 1597 } 1599 leaf start-time { 1600 type uint64; 1601 default 0; 1602 description 1603 "Time when the session is to be started 1604 (but not before the TWAMP Start-Sessions command 1605 is issued; see Section 3.4 of RFC 5357). 1607 The start-time value is placed in the Start Time 1608 field of the Request-TW-Session message. 1610 The timestamp format follows RFC 1305 as per 1611 Section 3.5 of RFC 4656. 1613 The default value of 0 indicates that the session 1614 will be started as soon as the Start-Sessions 1615 message is received."; 1616 } 1618 leaf repeat { 1619 type union { 1620 type uint32 { 1621 range 0..4294967294; 1622 } 1623 type enumeration { 1624 enum forever { 1625 description 1626 "Indicates that the test session SHALL be 1627 repeated *forever* using the information in 1628 repeat-interval parameter, and SHALL NOT 1629 decrement the value."; 1630 } 1631 } 1632 } 1633 default 0; 1634 description 1635 "This value determines if the TWAMP-Test session must 1636 be repeated. When a test session has completed, the 1637 repeat parameter is checked. 1639 The default value of 0 indicates that the session 1640 MUST NOT be repeated. 1642 If the repeat value is 1 through 4,294,967,294 1643 then the test session SHALL be repeated using the 1644 information in repeat-interval parameter, and the 1645 parent TWAMP-Control connection for this test 1646 session is restarted to negotiate a new instance 1647 of this TWAMP-Test session."; 1649 } 1651 leaf repeat-interval { 1652 when "../repeat!='0'" { 1653 description 1654 "This parameter determines the timing of repeated 1655 TWAMP-Test sessions when repeat is more than 0. 1657 When the value of repeat-interval is 0, the 1658 negotiation of a new test session SHALL begin 1659 immediately after the previous test session 1660 completes. Otherwise, the Control-Client will 1661 wait for the number of seconds specified in the 1662 repeat-interval parameter before negotiating the 1663 new instance of this TWAMP-Test session."; 1664 } 1665 type uint32; 1666 units seconds; 1667 default 0; 1668 description 1669 "Repeat interval (in seconds)."; 1670 } 1672 list pm-reg-list { 1673 key pm-index; 1674 leaf pm-index { 1675 type uint16; 1676 description 1677 "Numerical index value of a Registered Metric 1678 in the Performance Metric Registry 1679 (see ietf-ippm-metric-registry). Output statistics 1680 are specified in the corresponding Registry 1681 entry."; 1682 } 1683 description 1684 "A list of one or more Performance Metric Registry 1685 Index values, which communicate packet stream 1686 characteristics along with one or more metrics 1687 to be measured. 1689 All members of the pm-reg-list MUST have the same 1690 stream characteristics, such that they combine 1691 to specify all metrics that shall be measured on 1692 a single stream."; 1693 reference 1694 "ietf-ippm-metric-registry: Registry for 1695 Performance Metrics"; 1696 } 1697 leaf state { 1698 type test-session-state; 1699 config false; 1700 description 1701 "Indicates the TWAMP-Test session state, accepted or 1702 indication of an error."; 1703 reference 1704 "Section 3.5 of RFC 5357."; 1705 } 1706 leaf sid { 1707 type string; 1708 config false; 1709 description 1710 "The SID allocated by the Server for this TWAMP-Test 1711 session, and communicated back to the Control-Client 1712 in the SID field of the Accept-Session message"; 1713 reference 1714 "Section 4.3 of RFC 6038."; 1715 } 1716 } 1717 } 1718 } 1720 container server { 1721 if-feature server; 1722 description 1723 "Configuration of the TWAMP Server logical entity."; 1725 leaf admin-state { 1726 type boolean; 1727 default true; 1728 description 1729 "Indicates whether the device is allowed to operate 1730 as a TWAMP Server."; 1731 } 1733 leaf server-tcp-port { 1734 type inet:port-number; 1735 default 862; 1736 description 1737 "This parameter defines the well known TCP port number 1738 that is used by TWAMP-Control. The Server will listen 1739 on this port number for incoming TWAMP-Control 1740 connections. Although this is defined as a fixed value 1741 (862) in RFC 5357, there are several realizations of 1742 TWAMP in the field that were implemented before this 1743 well-known port number was allocated. These early 1744 implementations allowed the port number to be 1745 configured. This parameter is therefore provided for 1746 backward compatibility reasons."; 1747 } 1749 leaf servwait { 1750 type uint32 { 1751 range 1..604800; 1752 } 1753 units seconds; 1754 default 900; 1755 description 1756 "TWAMP-Control (TCP) session timeout, in seconds. 1757 According to Section 3.1 of RFC 5357, 1759 Server MAY discontinue any established control 1760 connection when no packet associated with that 1761 connection has been received within SERVWAIT seconds."; 1762 } 1764 leaf control-packet-dscp { 1765 type inet:dscp; 1766 description 1767 "The DSCP value to be placed in the IP header of 1768 TWAMP-Control (TCP) packets generated by the Server. 1770 Section 3.1 of RFC 5357 specifies that the server 1771 SHOULD use the DSCP value from the Control-Clients 1772 TCP SYN. However, for practical purposes TWAMP will 1773 typically be implemented using a general purpose TCP 1774 stack provided by the underlying operating system, 1775 and such a stack may not provide this information to the 1776 user. Consequently, it is not always possible to 1777 implement the behavior described in RFC 5357 in an 1778 OS-portable version of TWAMP. 1780 The default behavior if this item is not set is to use 1781 the DSCP value from the Control-Clients TCP SYN."; 1782 reference 1783 "Section 3.1 of RFC 5357."; 1784 } 1786 uses count; 1788 uses max-count-exponent; 1790 leaf modes { 1791 type twamp-modes; 1792 description 1793 "The bit mask of TWAMP Modes this Server instance 1794 is willing to support; see IANA TWAMP Modes Registry."; 1795 } 1797 uses key-management; 1799 list ctrl-connection { 1800 key "client-ip client-tcp-port server-ip server-tcp-port"; 1801 config false; 1802 description 1803 "List of all incoming TWAMP-Control (TCP) connections."; 1805 leaf client-ip { 1806 type inet:ip-address; 1807 description 1808 "The IP address on the remote Control-Client device, 1809 which is the source IP address used in the 1810 TWAMP-Control (TCP) packets belonging to this control 1811 connection."; 1812 } 1814 leaf client-tcp-port { 1815 type inet:port-number; 1816 description 1817 "The source TCP port number used in the TWAMP-Control 1818 (TCP) packets belonging to this control connection."; 1819 } 1821 leaf server-ip { 1822 type inet:ip-address; 1823 description 1824 "The IP address of the local Server device, which is 1825 the destination IP address used in the 1826 TWAMP-Control (TCP) packets belonging to this control 1827 connection."; 1828 } 1830 leaf server-tcp-port { 1831 type inet:port-number; 1832 description 1833 "The destination TCP port number used in the 1834 TWAMP-Control (TCP) packets belonging to this 1835 control connection. This will usually be the 1836 same value as the server-tcp-port configured 1837 under twamp/server. However, in the event that 1838 the user re-configured server/server-tcp-port 1839 after this control connection was initiated, this 1840 value will indicate the server-tcp-port that is 1841 actually in use for this control connection."; 1842 } 1844 leaf state { 1845 type server-ctrl-connection-state; 1846 description 1847 "Indicates the Server TWAMP-Control connection state."; 1848 } 1850 leaf control-packet-dscp { 1851 type inet:dscp; 1852 description 1853 "The DSCP value used in the IP header of the 1854 TWAMP-Control (TCP) packets sent by the Server 1855 for this control connection. This will usually 1856 be the same value as is configured in the 1857 control-packet-dscp parameter under the twamp/server 1858 container. However, in the event that the user 1859 re-configures server/dscp after this control 1860 connection is already in progress, this read-only 1861 value will show the actual dscp value in use by this 1862 TWAMP-Control connection."; 1863 } 1865 leaf selected-mode { 1866 type twamp-modes; 1867 description 1868 "The Mode that was chosen for this TWAMP-Control 1869 connection as set in the Mode field of the 1870 Set-Up-Response message."; 1871 } 1873 leaf key-id { 1874 type string { 1875 length 1..80; 1876 } 1877 description 1878 "The KeyID value that is in use by this TWAMP-Control 1879 connection as selected by Control-Client."; 1880 } 1882 uses count { 1883 description 1884 "The count value that is in use by this TWAMP-Control 1885 connection. This will usually be the same value 1886 as is configured under twamp/server. However, in the 1887 event that the user re-configured server/count 1888 after this control connection is already in progress, 1889 this read-only value will show the actual count that 1890 is in use for this TWAMP-Control connection."; 1891 } 1893 uses max-count-exponent { 1894 description 1895 "This read-only value indicates the actual max-count in 1896 use for this control connection. Usually this would be 1897 the same value as configured under twamp/server."; 1898 } 1900 leaf salt { 1901 type binary { 1902 length 16; 1903 } 1904 description 1905 "A parameter used in deriving a key from a 1906 shared secret as described in Section 3.1 of RFC 4656. 1907 It is communicated to the Control-Client as part of 1908 the Server Greeting message."; 1909 } 1911 leaf server-iv { 1912 type binary { 1913 length 16; 1914 } 1915 description 1916 "The Server Initialization Vector 1917 (IV) generated randomly by the Server."; 1918 } 1920 leaf challenge { 1921 type binary { 1922 length 16; 1923 } 1924 description 1925 "A random sequence of octets generated by the Server. 1926 As described in client/token, Challenge is used 1927 by the Control-Client to prove possession of a 1928 shared secret."; 1929 } 1930 } 1931 } 1933 container session-sender { 1934 if-feature session-sender; 1935 description 1936 "Configuration of the TWAMP Session-Sender logical entity"; 1938 leaf admin-state { 1939 type boolean; 1940 default true; 1941 description 1942 "Indicates whether the device is allowed to operate 1943 as a TWAMP Session-Sender."; 1944 } 1946 list test-session{ 1947 key name; 1948 description 1949 "List of TWAMP Session-Sender test sessions."; 1951 leaf name { 1952 type string; 1953 description 1954 "A unique name for this TWAMP-Test session to be used 1955 for identifying this test session by the 1956 Session-Sender logical entity."; 1957 } 1959 leaf ctrl-connection-name { 1960 type string; 1961 config false; 1962 description 1963 "The name of the parent TWAMP-Control connection that 1964 is responsible for negotiating this TWAMP-Test 1965 session."; 1966 } 1968 leaf fill-mode { 1969 type padding-fill-mode; 1970 default zero; 1971 description 1972 "Indicates whether the padding added to the 1973 TWAMP-Test (UDP) packets will contain pseudo-random 1974 numbers, or whether it should consist of all zeroes, 1975 as per Section 4.2.1 of RFC 5357."; 1976 } 1978 leaf number-of-packets { 1979 type uint32; 1980 mandatory true; 1981 description 1982 "The overall number of TWAMP-Test (UDP) packets to be 1983 transmitted by the Session-Sender for this test 1984 session."; 1985 } 1986 choice packet-distribution { 1987 description 1988 "Indicates the distribution to be used for transmitting 1989 the TWAMP-Test (UDP) packets."; 1990 case periodic { 1991 leaf periodic-interval { 1992 type decimal64 { 1993 fraction-digits 5; 1994 } 1995 units seconds; 1996 mandatory true; 1997 description 1998 "Indicates the time to wait (in seconds) between 1999 the first bits of TWAMP-Test (UDP) packet 2000 transmissions for this test session."; 2001 reference 2002 "RFC 3432: Network performance measurement 2003 with periodic streams"; 2004 } 2005 } 2006 case poisson { 2007 leaf lambda { 2008 type decimal64 { 2009 fraction-digits 5; 2010 } 2011 units seconds; 2012 mandatory true; 2013 description 2014 "Indicates the average time interval (in seconds) 2015 between packets in the Poisson distribution. 2016 The packet is calculated using the reciprocal of 2017 lambda and the TWAMP-Test packet size (which 2018 depends on the selected Mode and the packet 2019 padding)."; 2020 reference 2021 "RFC 2330: Framework for IP Performance Metrics"; 2022 } 2023 leaf max-interval { 2024 type decimal64 { 2025 fraction-digits 5; 2026 } 2027 units seconds; 2028 description 2029 "Indicates the maximum time (in seconds) 2030 between packet transmissions."; 2031 reference 2032 "RFC 7312: Advanced Stream and Sampling Framework 2033 for IP Performance Metrics (IPPM)"; 2035 } 2036 } 2037 } 2039 leaf state { 2040 type sender-session-state; 2041 config false; 2042 description 2043 "Indicates the Session-Sender test session state."; 2044 } 2046 uses maintenance-statistics; 2047 } 2048 } 2050 container session-reflector { 2051 if-feature session-reflector; 2052 description 2053 "Configuration of the TWAMP Session-Reflector logical 2054 entity"; 2056 leaf admin-state { 2057 type boolean; 2058 default true; 2059 description 2060 "Indicates whether the device is allowed to operate 2061 as a TWAMP Session-Reflector."; 2062 } 2064 leaf refwait { 2065 type uint32 { 2066 range 1..604800; 2067 } 2068 units seconds; 2069 default 900; 2070 description 2071 "The Session-Reflector MAY discontinue any session that 2072 has been started when no packet associated with that 2073 session has been received for REFWAIT seconds. As per 2074 Section 3.1 of RFC 5357, this timeout allows a 2075 Session-Reflector to free up resources in case of 2076 failure."; 2077 } 2079 list test-session { 2080 key 2081 "sender-ip sender-udp-port 2082 reflector-ip reflector-udp-port"; 2084 config false; 2085 description 2086 "TWAMP Session-Reflectortest sessions."; 2088 leaf sid { 2089 type string; 2090 description 2091 "An auto-allocated identifier for this TWAMP-Test 2092 session that is unique within the context of this 2093 Server/Session-Reflector device only. This value 2094 is communicated to the Control-Client that 2095 requested the test session in the SID field of the 2096 Accept-Session message."; 2097 } 2099 leaf sender-ip { 2100 type inet:ip-address; 2101 description 2102 "The IP address on the remote device, which is the 2103 source IP address used in the TWAMP-Test (UDP) packets 2104 belonging to this test session."; 2105 } 2107 leaf sender-udp-port { 2108 type dynamic-port-number; 2109 description 2110 "The source UDP port used in the TWAMP-Test packets 2111 belonging to this test session."; 2112 } 2114 leaf reflector-ip { 2115 type inet:ip-address; 2116 description 2117 "The IP address of the local Session-Reflector 2118 device, which is the destination IP address used 2119 in the TWAMP-Test (UDP) packets belonging to this test 2120 session."; 2121 } 2123 leaf reflector-udp-port { 2124 type inet:port-number { 2125 range "862 | 49152..65535"; 2126 } 2127 description 2128 "The destination UDP port number used in the 2129 TWAMP-Test (UDP) test packets belonging to this 2130 test session."; 2131 } 2132 leaf parent-connection-client-ip { 2133 type inet:ip-address; 2134 description 2135 "The IP address on the Control-Client device, which 2136 is the source IP address used in the TWAMP-Control 2137 (TCP) packets belonging to the parent control 2138 connection that negotiated this test session."; 2139 } 2141 leaf parent-connection-client-tcp-port { 2142 type inet:port-number; 2143 description 2144 "The source TCP port number used in the TWAMP-Control 2145 (TCP) packets belonging to the parent control 2146 connection that negotiated this test session."; 2147 } 2149 leaf parent-connection-server-ip { 2150 type inet:ip-address; 2151 description 2152 "The IP address of the Server device, which is the 2153 destination IP address used in the TWAMP-Control 2154 (TCP) packets belonging to the parent control 2155 connection that negotiated this test session."; 2156 } 2158 leaf parent-connection-server-tcp-port { 2159 type inet:port-number; 2160 description 2161 "The destination TCP port number used in the 2162 TWAMP-Control (TCP) packets belonging to the parent 2163 control connection that negotiated this test 2164 session."; 2165 } 2167 leaf test-packet-dscp { 2168 type inet:dscp; 2169 description 2170 "The DSCP value present in the IP header of 2171 TWAMP-Test (UDP) packets belonging to this session."; 2172 } 2174 uses maintenance-statistics; 2175 } 2176 } 2177 } 2178 } 2179 2181 6. Data Model Examples 2183 This section presents a simple but complete example of configuring 2184 all four entities in Figure 1, based on the YANG module specified in 2185 Section 5. The example is illustrative in nature, but aims to be 2186 self-contained, i.e. were it to be executed in a real TWAMP 2187 implementation it would lead to a correctly configured test session. 2188 For completeness, examples are provided for both IPv4 and IPv6. 2190 A more elaborated example, which also includes authentication 2191 parameters, is provided in Appendix A. 2193 6.1. Control-Client 2195 Figure 8 shows a configuration example for a Control-Client with 2196 client/admin-state enabled. In a real implementation following 2197 Figure 2 this would permit the initiation of TWAMP-Control 2198 connections and TWAMP-Test sessions. 2200 [note: '\' line wrapping is for formatting only] 2202 2203 2204 2205 2206 true 2207 2208 2209 2211 Figure 8: XML instance enabling Control-Client operation. 2213 The following example shows a Control-Client with two instances of 2214 client/ctrl-connection, one called "RouterA" and another called 2215 "RouterB". Each TWAMP-Control connection is to a different Server. 2216 The control connection named "RouterA" has two test session requests. 2217 The TWAMP-Control connection named "RouterB" has no TWAMP-Test 2218 session requests. 2220 [note: '\' line wrapping is for formatting only] 2222 2223 2224 2225 2226 true 2227 2228 RouterA 2229 203.0.113.1 2230 203.0.113.2 2231 2232 Test1 2233 203.0.113.3 2234 54001 2235 203.0.113.4 2236 50001 2237 0 2238 2239 2240 Test2 2241 203.0.113.1 2242 54001 2243 203.0.113.2 2244 50001 2245 0 2246 2247 2248 2249 RouterB 2250 203.0.113.1 2251 203.0.113.3 2252 2253 2254 2255 2257 [note: '\' line wrapping is for formatting only] 2259 2260 2261 2262 2263 true 2264 2265 RouterA 2266 2001:DB8:203:0:113::1 2267 2001:DB8:203:0:113::2 2268 2269 Test1 2270 2001:DB8:203:1:113::3 2271 54000 2272 2001:DB8:203:1:113::4 2273 55000 2274 0 2275 2276 2277 Test2 2278 2001:DB8:203:0:113::1 2279 54001 2280 2001:DB8:203:0:113::2 2281 55001 2282 0 2283 2284 2285 2286 RouterB 2287 2001:DB8:203:0:113::1 2288 2001:DB8:203:0:113::3 2289 2290 2291 2292 2294 6.2. Server 2296 Figure 9 shows a configuration example for a Server with server/ 2297 admin-state enabled, which permits a device following Figure 2 to 2298 respond to TWAMP-Control connections and TWAMP-Test sessions. 2300 [note: '\' line wrapping is for formatting only] 2302 2303 2304 2305 2306 true 2307 2308 2309 2311 Figure 9: XML instance enabling Server operation. 2313 The following example presents a Server with the TWAMP-Control 2314 connection corresponding to the control connection name (client/ctrl- 2315 connection/name) "RouterA" presented in Section 6.1. 2317 [note: '\' line wrapping is for formatting only] 2319 2320 2321 2322 2323 true 2324 2325 203.0.113.1 2326 16341 2327 203.0.113.2 2328 862 2329 active 2330 2331 2332 2333 2335 [note: '\' line wrapping is for formatting only] 2337 2338 2339 2340 2341 true 2342 2343 2001:DB8:203:0:113::1 2344 16341 2345 2001:DB8:203:0:113::2 2346 862 2347 active 2348 2349 2350 2351 2353 6.3. Session-Sender 2355 Figure 10 shows a configuration example for a Session-Sender with 2356 session-sender/admin-state enabled, which permits a device following 2357 Figure 2 to initiate TWAMP-Test sessions. 2359 [note: '\' line wrapping is for formatting only] 2361 2362 2363 2364 2365 true 2366 2367 2368 2370 Figure 10: XML instance enabling Session-Sender operation. 2372 The following configuration example shows a Session-Sender with the 2373 two TWAMP-Test sessions presented in Section 6.1. 2375 [note: '\' line wrapping is for formatting only] 2377 2378 2379 2380 2381 true 2382 2383 Test1 2384 RouterA 2385 900 2386 1 2387 2388 2389 Test2 2390 RouterA 2391 900 2392 1 2393 2 2394 2395 2396 2397 2399 6.4. Session-Reflector 2401 This configuration example shows a Session-Reflector with session- 2402 reflector/admin-state enabled, which permits a device following 2403 Figure 2 to respond to TWAMP-Test sessions. 2405 [note: '\' line wrapping is for formatting only] 2407 2408 2409 2410 2411 true 2412 2413 2414 2416 Figure 11: XML instance enabling Session-Reflector operation. 2418 The following example shows the two Session-Reflector TWAMP-Test 2419 sessions corresponding to the test sessions presented in Section 6.3. 2421 [note: '\' line wrapping is for formatting only] 2423 2424 2425 2426 2427 true 2428 2429 203.0.113.3 2430 54000 2431 203.0.113.4 2432 50001 2433 1232 2434 203.0.113.1 2436 16341 2438 203.0.113.2 2440 862 2442 2 2443 2 2444 1 2445 1 2446 2447 2448 203.0.113.1 2449 54001 2450 192.68.0.2 2451 50001 2452 178943 2453 203.0.113.1 2455 16341 2457 203.0.113.2 2459 862 2461 21 2462 21 2463 20 2464 20 2465 2466 2467 2468 2470 [note: '\' line wrapping is for formatting only] 2472 2473 2474 2475 2476 true 2477 2478 203.0.113.3 2479 54000 2480 203.0.113.4 2481 54001 2482 1232 2483 203.0.113.1 2485 16341 2487 203.0.113.2 2489 862 2491 2 2492 2 2493 1 2494 1 2495 2496 2497 203.0.113.1 2498 54001 2499 192.68.0.2 2500 55001 2501 178943 2502 203.0.113.1 2504 16341 2506 203.0.113.2 2508 862 2510 21 2511 21 2512 20 2513 20 2514 2515 2516 2517 2519 7. Security Considerations 2521 The YANG module specified in Section 5 this document defines a schema 2522 for data that is designed to be accessed via network management 2523 protocols such as NETCONF [RFC6241] or RESTCONF [RFC8040]. The 2524 lowest NETCONF [RFC6241] layer is the secure transport layer, and the 2525 mandatory-to-implement secure transport is Secure Shell (SSH) 2526 [RFC6242]. The lowest RESTCONF layer is HTTPS, and the mandatory-to- 2527 implement secure transport is TLS [RFC5246]. 2529 The NETCONF Access Control Module (NACM) [RFC8341] provides the means 2530 to restrict access for particular NETCONF or RESTCONF users to a 2531 preconfigured subset of all available NETCONF or RESTCONF protocol 2532 operations and content.. 2534 There are a number of nodes defined in this YANG module which are 2535 writeable. These data nodes may be considered sensitive and 2536 vulnerable to attacks in some network environments. Ability to write 2537 into these nodes without proper protection can have a negative effect 2538 on the devices that support this feature. 2540 Examples of nodes that are particularly vulnerable include several 2541 timeout values put in the protocol to protect against sessions that 2542 are not active but are consuming resources. Limiting access to these 2543 nodes will limit the ability to launch an attack in network 2544 environments. 2546 8. IANA Considerations 2548 This document registers a URI in the IETF XML registry [RFC3688]. 2549 Following the format in IETF XML Registry [RFC3688], the following 2550 registration is requested to be made. 2552 URI: urn:ietf:params:xml:ns:yang:ietf-twamp 2554 Registrant Contact: The IPPM WG of the IETF. 2556 XML: N/A, the requested URI is an XML namespace. 2558 This document registers a YANG module in the YANG Module Names 2559 registry YANG [RFC6020]. 2561 name: ietf-twamp 2563 namespace: urn:ietf:params:xml:ns:yang:ietf-twamp 2565 prefix: twamp 2567 reference: RFC XXXX 2569 9. Acknowledgements 2571 We thank Fred Baker, Kevin D'Souza, Gregory Mirsky, Brian Trammell, 2572 Robert Sherman, and Marius Georgescu for their thorough and 2573 constructive reviews, comments and text suggestions. 2575 Haoxing Shen contributed to the definition of the YANG module in 2576 Section 5. 2578 Jan Lindblad and Ladislav Lhokta did thorough reviews of the YANG 2579 module and the examples in Appendix A. 2581 Kostas Pentikousis was partially supported by FP7 UNIFY 2582 (http://fp7-unify.eu), a research project partially funded by the 2583 European Community under the Seventh Framework Program (grant 2584 agreement no. 619609). The views expressed here are those of the 2585 authors only. The European Commission is not liable for any use that 2586 may be made of the information in this document. 2588 10. Contributors 2590 Lianshu Zheng. 2592 11. References 2594 11.1. Normative References 2596 [I-D.ietf-ippm-metric-registry] 2597 Bagnulo, M., Claise, B., Eardley, P., Morton, A., and A. 2598 Akhter, "Registry for Performance Metrics", draft-ietf- 2599 ippm-metric-registry-14 (work in progress), March 2018. 2601 [I-D.ietf-ippm-port-twamp-test] 2602 Morton, A. and G. Mirsky, "OWAMP and TWAMP Well-Known Port 2603 Assignments", draft-ietf-ippm-port-twamp-test-01 (work in 2604 progress), March 2018. 2606 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2607 Requirement Levels", BCP 14, RFC 2119, 2608 DOI 10.17487/RFC2119, March 1997, 2609 . 2611 [RFC3432] Raisanen, V., Grotefeld, G., and A. Morton, "Network 2612 performance measurement with periodic streams", RFC 3432, 2613 DOI 10.17487/RFC3432, November 2002, 2614 . 2616 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2617 DOI 10.17487/RFC3688, January 2004, 2618 . 2620 [RFC4086] Eastlake 3rd, D., Schiller, J., and S. Crocker, 2621 "Randomness Requirements for Security", BCP 106, RFC 4086, 2622 DOI 10.17487/RFC4086, June 2005, 2623 . 2625 [RFC4656] Shalunov, S., Teitelbaum, B., Karp, A., Boote, J., and M. 2626 Zekauskas, "A One-way Active Measurement Protocol 2627 (OWAMP)", RFC 4656, DOI 10.17487/RFC4656, September 2006, 2628 . 2630 [RFC5357] Hedayat, K., Krzanowski, R., Morton, A., Yum, K., and J. 2631 Babiarz, "A Two-Way Active Measurement Protocol (TWAMP)", 2632 RFC 5357, DOI 10.17487/RFC5357, October 2008, 2633 . 2635 [RFC5905] Mills, D., Martin, J., Ed., Burbank, J., and W. Kasch, 2636 "Network Time Protocol Version 4: Protocol and Algorithms 2637 Specification", RFC 5905, DOI 10.17487/RFC5905, June 2010, 2638 . 2640 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2641 the Network Configuration Protocol (NETCONF)", RFC 6020, 2642 DOI 10.17487/RFC6020, October 2010, 2643 . 2645 [RFC6038] Morton, A. and L. Ciavattone, "Two-Way Active Measurement 2646 Protocol (TWAMP) Reflect Octets and Symmetrical Size 2647 Features", RFC 6038, DOI 10.17487/RFC6038, October 2010, 2648 . 2650 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 2651 RFC 6991, DOI 10.17487/RFC6991, July 2013, 2652 . 2654 [RFC7717] Pentikousis, K., Ed., Zhang, E., and Y. Cui, 2655 "IKEv2-Derived Shared Secret Key for the One-Way Active 2656 Measurement Protocol (OWAMP) and Two-Way Active 2657 Measurement Protocol (TWAMP)", RFC 7717, 2658 DOI 10.17487/RFC7717, December 2015, 2659 . 2661 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2662 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2663 . 2665 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2666 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2667 May 2017, . 2669 11.2. Informative References 2671 [I-D.unify-nfvrg-challenges] 2672 Szabo, R., Csaszar, A., Pentikousis, K., Kind, M., Daino, 2673 D., Qiang, Z., and H. Woesner, "Unifying Carrier and Cloud 2674 Networks: Problem Statement and Challenges", draft-unify- 2675 nfvrg-challenges-04 (work in progress), July 2016. 2677 [I-D.unify-nfvrg-devops] 2678 Meirosu, C., Manzalini, A., Steinert, R., Marchetto, G., 2679 Pentikousis, K., Wright, S., Lynch, P., and W. John, 2680 "DevOps for Software-Defined Telecom Infrastructures", 2681 draft-unify-nfvrg-devops-06 (work in progress), July 2016. 2683 [NSC] John, W., Pentikousis, K., et al., "Research directions in 2684 network service chaining", Proc. SDN for Future Networks 2685 and Services (SDN4FNS), Trento, Italy IEEE, November 2013. 2687 [RFC2330] Paxson, V., Almes, G., Mahdavi, J., and M. Mathis, 2688 "Framework for IP Performance Metrics", RFC 2330, 2689 DOI 10.17487/RFC2330, May 1998, 2690 . 2692 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2693 (TLS) Protocol Version 1.2", RFC 5246, 2694 DOI 10.17487/RFC5246, August 2008, 2695 . 2697 [RFC5618] Morton, A. and K. Hedayat, "Mixed Security Mode for the 2698 Two-Way Active Measurement Protocol (TWAMP)", RFC 5618, 2699 DOI 10.17487/RFC5618, August 2009, 2700 . 2702 [RFC5938] Morton, A. and M. Chiba, "Individual Session Control 2703 Feature for the Two-Way Active Measurement Protocol 2704 (TWAMP)", RFC 5938, DOI 10.17487/RFC5938, August 2010, 2705 . 2707 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2708 and A. Bierman, Ed., "Network Configuration Protocol 2709 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2710 . 2712 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 2713 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 2714 . 2716 [RFC7312] Fabini, J. and A. Morton, "Advanced Stream and Sampling 2717 Framework for IP Performance Metrics (IPPM)", RFC 7312, 2718 DOI 10.17487/RFC7312, August 2014, 2719 . 2721 [RFC7426] Haleplidis, E., Ed., Pentikousis, K., Ed., Denazis, S., 2722 Hadi Salim, J., Meyer, D., and O. Koufopavlou, "Software- 2723 Defined Networking (SDN): Layers and Architecture 2724 Terminology", RFC 7426, DOI 10.17487/RFC7426, January 2725 2015, . 2727 [RFC8018] Moriarty, K., Ed., Kaliski, B., and A. Rusch, "PKCS #5: 2728 Password-Based Cryptography Specification Version 2.1", 2729 RFC 8018, DOI 10.17487/RFC8018, January 2017, 2730 . 2732 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2733 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2734 . 2736 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 2737 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 2738 . 2740 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 2741 Access Control Model", STD 91, RFC 8341, 2742 DOI 10.17487/RFC8341, March 2018, 2743 . 2745 Appendix A. Detailed Data Model Examples 2747 This appendix extends the example presented in Section 6 by 2748 configuring more fields such as authentication parameters, DSCP 2749 values and so on. 2751 A.1. Control-Client 2753 [note: '\' line wrapping is for formatting only] 2755 2756 2757 2758 2759 true 2760 2761 0 2762 authenticated 2763 2764 2765 1 2766 unauthenticated 2767 2768 2769 KeyClient1ToRouterA 2770 c2VjcmV0MQ== 2771 2772 2773 KeyForRouterB 2774 c2VjcmV0Mg0K 2775 2776 2777 RouterA 2778 203.0.113.1 2779 203.0.113.2 2780 32 2781 KeyClient1ToRouterA 2782 2783 Test1 2784 203.0.113.3 2785 54000 2786 203.0.113.4 2787 55000 2788 64 2789 0 2790 2791 2792 Test2 2793 203.0.113.1 2794 54001 2795 203.0.113.2 2796 55001 2797 128 2798 0 2799 2800 2801 2802 2803 2805 [note: '\' line wrapping is for formatting only] 2807 2808 2809 2810 2811 true 2812 2813 0 2814 authenticated 2815 2816 2817 1 2818 unauthenticated 2819 2820 2821 KeyClient1ToRouterA 2822 c2VjcmV0MQ== 2823 2824 2825 KeyForRouterB 2826 c2VjcmV0Mg0K 2827 2828 2829 RouterA 2830 2001:DB8:203:0:113::1 2831 2001:DB8:203:0:113::2 2832 32 2833 KeyClient1ToRouterA 2834 2835 Test1 2836 2001:DB8:10:1:1::1 2837 54000 2838 2001:DB8:10:1:1::2 2839 55000 2840 64 2841 0 2842 2843 2844 Test2 2845 2001:DB8:203:0:113::1 2846 54001 2847 2001:DB8:203:0:113::2 2848 55001 2849 128 2850 0 2851 2852 2853 2854 2855 2857 A.2. Server 2859 [note: '\' line wrapping is for formatting only] 2861 2862 2863 2864 2865 true 2866 1800 2867 32 2868 authenticated unauthenticated 2869 30 2870 2871 KeyClient1ToRouterA 2872 c2VjcmV0MQ== 2873 2874 2875 KeyClient10ToRouterA 2876 c2VjcmV0MTANCg== 2877 2878 2879 203.0.113.1 2880 16341 2881 203.0.113.2 2882 862 2883 32 2884 unauthenticated 2885 KeyClient1ToRouterA 2886 30 2887 2888 2889 2890 2892 [note: '\' line wrapping is for formatting only] 2894 2895 2896 2897 2898 true 2899 1800 2900 32 2901 authenticated unauthenticated 2902 30 2903 2904 KeyClient1ToRouterA 2905 c2VjcmV0MQ== 2906 2907 2908 KeyClient10ToRouterA 2909 c2VjcmV0MTANCg== 2910 2911 2912 2001:DB8:203:0:113::1 2913 16341 2914 2001:DB8:203:0:113::2 2915 862 2916 32 2917 unauthenticated 2918 KeyClient1ToRouterA 2919 30 2920 2921 2922 2923 2925 A.3. Session-Sender 2927 [note: '\' line wrapping is for formatting only] 2929 2930 2931 2932 2933 true 2934 2935 Test1 2936 RouterA 2937 zero 2938 900 2939 1 2940 2 2941 2 2942 1 2943 1 2944 2945 2946 Test2 2947 RouterA 2948 random 2949 900 2950 1 2951 2 2952 21 2953 21 2954 20 2955 20 2956 2957 2958 2959 2961 A.4. Session-Reflector 2963 [note: '\' line wrapping is for formatting only] 2965 2966 2967 2968 2969 true 2970 2971 203.0.113.3 2972 54000 2973 203.0.113.4 2974 55000 2975 1232 2976 203.0.113.1 2978 16341 2980 203.0.113.2 2982 862 2984 32 2985 2 2986 2 2987 1 2988 1 2989 2990 2991 203.0.113.1 2992 54001 2993 192.68.0.2 2994 55001 2995 178943 2996 203.0.113.1 2998 16341 3000 203.0.113.2 3002 862 3004 32 3005 21 3006 21 3007 20 3008 20 3009 3010 3011 3012 3014 [note: '\' line wrapping is for formatting only] 3016 3017 3018 3019 3020 true 3021 3022 2001:DB8:10:1:1::1 3023 54000 3024 2001:DB8:10:1:1::2 3025 55000 3026 1232 3027 2001:DB8:203:0:113::1 3029 16341 3031 2001:DB8:203:0:113::2 3033 862 3035 32 3036 2 3037 2 3038 1 3039 1 3040 3041 3042 2001:DB8:203:0:113::1 3043 54001 3044 2001:DB8:192:68::2 3045 55001 3046 178943 3047 2001:DB8:203:0:113::1 3049 16341 3051 2001:DB8:203:0:113::2 3053 862 3055 32 3056 21 3057 21 3058 20 3059 20 3060 3061 3062 3063 3065 Appendix B. TWAMP Operational Commands 3067 TWAMP operational commands could be performed programmatically or 3068 manually, e.g. using a command-line interface (CLI). 3070 With respect to programmability, YANG can be used to define NETCONF 3071 Remote Procedure Calls (RPC), therefore it would be, in principle, 3072 possible to define TWAMP RPC operations for actions such as starting 3073 or stopping control connections or test sessions or groups of 3074 sessions; retrieving results; clearing stored results, and so on. 3076 However, TWAMP [RFC5357] does not attempt to describe such 3077 operational actions. Refer also to Section 2 and the unlabeled links 3078 in Figure 1. In actual deployments different TWAMP implementations 3079 may support different sets of operational commands, with different 3080 restrictions. Therefore, this document considers it the 3081 responsibility of the individual implementation to define its 3082 corresponding TWAMP operational commands data model. 3084 Authors' Addresses 3086 Ruth Civil 3087 Ciena Corporation 3088 307 Legget Drive 3089 Kanata, ON K2K 3C8 3090 Canada 3092 Email: gcivil@ciena.com 3093 URI: www.ciena.com 3095 Al Morton 3096 AT&T Labs 3097 200 Laurel Avenue South 3098 Middletown,, NJ 07748 3099 USA 3101 Phone: +1 732 420 1571 3102 Fax: +1 732 368 1192 3103 Email: acmorton@att.com 3104 Reshad Rahman 3105 Cisco Systems 3106 2000 Innovation Drive 3107 Kanata, ON K2K 3E8 3108 Canada 3110 Email: rrahman@cisco.com 3112 Mahesh Jethanandani 3114 Email: mjethanandani@gmail.com 3116 Kostas Pentikousis (editor) 3117 Travelping 3118 Siemensdamm 50 3119 Berlin 13629 3120 Germany 3122 Email: k.pentikousis@travelping.com