idnits 2.17.1 draft-ietf-ippm-twamp-yang-07.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 663 has weird spacing: '...riority uin...' == Line 697 has weird spacing: '...m-index uin...' -- The document date (April 8, 2018) is 2200 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 Summary: 0 errors (**), 0 flaws (~~), 4 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 IPPM WG R. Civil 3 Internet-Draft Ciena Corporation 4 Intended status: Standards Track A. Morton 5 Expires: October 10, 2018 AT&T Labs 6 R. Rahman 7 Cisco Systems 8 M. Jethanandani 10 K. Pentikousis, Ed. 11 Travelping 12 April 8, 2018 14 Two-Way Active Measurement Protocol (TWAMP) Data Model 15 draft-ietf-ippm-twamp-yang-07 17 Abstract 19 This document specifies a data model for client and server 20 implementations of the Two-Way Active Measurement Protocol (TWAMP). 21 We define the TWAMP data model through Unified Modeling Language 22 (UML) class diagrams and formally specify it using YANG. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at https://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on October 10, 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 . . . . . . . . . . . . . . . . . . . . . . . 3 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 . . . . . . . . . . . . . . . . . . . . 7 68 4. Data Model Parameters . . . . . . . . . . . . . . . . . . . . 8 69 4.1. Control-Client . . . . . . . . . . . . . . . . . . . . . 8 70 4.2. Server . . . . . . . . . . . . . . . . . . . . . . . . . 11 71 4.3. Session-Sender . . . . . . . . . . . . . . . . . . . . . 12 72 4.4. Session-Reflector . . . . . . . . . . . . . . . . . . . . 13 73 5. Data Model . . . . . . . . . . . . . . . . . . . . . . . . . 15 74 5.1. YANG Tree Diagram . . . . . . . . . . . . . . . . . . . . 15 75 5.2. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 18 76 6. Data Model Examples . . . . . . . . . . . . . . . . . . . . . 46 77 6.1. Control-Client . . . . . . . . . . . . . . . . . . . . . 47 78 6.2. Server . . . . . . . . . . . . . . . . . . . . . . . . . 49 79 6.3. Session-Sender . . . . . . . . . . . . . . . . . . . . . 50 80 6.4. Session-Reflector . . . . . . . . . . . . . . . . . . . . 51 81 7. Security Considerations . . . . . . . . . . . . . . . . . . . 54 82 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 54 83 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 55 84 10. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 55 85 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 55 86 11.1. Normative References . . . . . . . . . . . . . . . . . . 55 87 11.2. Informative References . . . . . . . . . . . . . . . . . 57 88 Appendix A. Detailed Data Model Examples . . . . . . . . . . . . 58 89 A.1. Control-Client . . . . . . . . . . . . . . . . . . . . . 58 90 A.2. Server . . . . . . . . . . . . . . . . . . . . . . . . . 60 91 A.3. Session-Sender . . . . . . . . . . . . . . . . . . . . . 62 92 A.4. Session-Reflector . . . . . . . . . . . . . . . . . . . . 62 93 Appendix B. TWAMP Operational Commands . . . . . . . . . . . . . 65 94 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 65 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. 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 [I-D.unify-nfvrg-challenges][I-D.unify-nfvrg-devops], 115 proprietary mechanisms for managing TWAMP measurements pose severe 116 limitations with respect to programmability. 118 Two major trends call for standardizing TWAMP management aspects. 119 First, we expect that in the coming years large-scale and multi- 120 vendor TWAMP deployments will become the norm. From an operations 121 perspective, using several vendor-specific TWAMP configuration 122 mechanisms when one standard mechanism could provide an alternative 123 is expensive and inefficient. Second, the increasingly software- 124 defined and virtualized nature of network infrastructures, based on 125 dynamic service chains [NSC] and programmable control and management 126 planes [RFC7426] requires a well-defined data model for TWAMP 127 implementations. This document defines such a TWAMP data model and 128 specifies it formally using the YANG data modeling language 129 [RFC7950]. 131 Note to RFC Editor: 133 Please replace the date 2018-04-08 in Section 5.2 of the draft with 134 the date of publication of this draft as a RFC. Also, replace 135 reference to RFC XXXX, and draft-ietf-ippm-metric-registry with the 136 RFC numbers assigned to the draft. 138 1.2. Terminology 140 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 141 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 142 "OPTIONAL" in this document are to be interpreted as described in BCP 143 14 [RFC2119] [RFC8174] when, and only when, they appear in all 144 capitals, as shown here. 146 1.3. Document Organization 148 The rest of this document is organized as follows. Section 2 149 presents the scope and applicability of this document. Section 3 150 provides a high-level overview of the TWAMP data model. Section 4 151 details the configuration parameters of the data model and Section 5 152 specifies in YANG the TWAMP data model. Section 6 lists illustrative 153 examples which conform to the YANG data model specified in this 154 document. Appendix A elaborates these examples further. 156 2. Scope, Model, and Applicability 158 The purpose of this document is the specification of a vendor- 159 independent data model for TWAMP implementations. 161 Figure 1 illustrates a redrawn version of the TWAMP logical model 162 found in Section 1.2 of [RFC5357]. The figure is annotated with 163 pointers to the UML diagrams provided in this document and associated 164 with the data model of the four logical entities in a TWAMP 165 deployment, namely the TWAMP Control-Client, Server, Session-Sender 166 and Session-Reflector. 168 As per [RFC5357], unlabeled links in Figure 1 are left unspecified 169 and may be proprietary protocols. 171 [Fig. 3] [Fig. 4] 172 +----------------+ +--------+ 173 | Control-Client | <-- TWAMP-Control --> | Server | 174 +----------------+ +--------+ 175 ^ ^ 176 | | 177 V V 178 +----------------+ +-------------------+ 179 | Session-Sender | <-- TWAMP-Test --> | Session-Reflector | 180 +----------------+ +-------------------+ 181 [Fig. 5] [Fig. 6] 183 Figure 1: Annotated TWAMP logical model 185 As per [RFC5357], a TWAMP implementation may follow a simplified 186 logical model, in which the same node acts both as Control-Client and 187 Session-Sender, while another node acts at the same time as TWAMP 188 Server and Session-Reflector. Figure 2 illustrates this simplified 189 logical model and indicates the interaction between the TWAMP 190 configuration client and server using, for instance, NETCONF 191 [RFC6241] or RESTCONF [RFC8040]. 193 o-------------------o o-------------------o 194 | Config client | | Config client | 195 o-------------------o o-------------------o 196 || || 197 NETCONF || RESTCONF NETCONF || RESTCONF 198 || || 199 o-------------------o o-------------------o 200 | Config server | | Config server | 201 | [Fig. 3, 5] | | [Fig. 4, 6] | 202 +-------------------+ +-------------------+ 203 | Control-Client | <-- TWAMP-Control --> | Server | 204 | | | | 205 | Session-Sender | <-- TWAMP-Test --> | Session-Reflector | 206 +-------------------+ +-------------------+ 208 Figure 2: Simplified TWAMP model and protocols 210 The data model defined in this document is orthogonal to the specific 211 protocol used between the Config client and Config server to 212 communicate the TWAMP configuration parameters. 214 Operational actions such as how TWAMP-Test sessions are started and 215 stopped, how performance measurement results are retrieved, or how 216 stored results are cleared, and so on, are not addressed by the 217 configuration model defined in this document. As noted above, such 218 operational actions are not part of the TWAMP specification [RFC5357] 219 and hence are out of scope of this document. See also Appendix B. 221 3. Data Model Overview 223 The TWAMP data model includes four categories of configuration items. 225 First, global configuration items relate to parameters that are set 226 on a per device level. For example, the administrative status of the 227 device with respect to whether it allows TWAMP sessions and, if so, 228 in what capacity (e.g. Control-Client, Server or both), is a typical 229 instance of a global configuration item. 231 A second category includes attributes that can be configured on a per 232 TWAMP-Control connection basis, such as the Server IP address. 234 A third category includes attributes related to per TWAMP-Test 235 session attributes, for instance setting different values in the 236 Differentiated Services Code Point (DSCP) field. 238 Finally, the data model includes attributes that relate to the 239 operational state of the TWAMP implementation. 241 As we describe the TWAMP data model in the remaining sections of this 242 document, readers should keep in mind the functional entity grouping 243 illustrated in Figure 1. 245 3.1. Control-Client 247 A TWAMP Control-Client has an administrative status field set at the 248 device level that indicates whether the node is enabled to function 249 as such. 251 Each TWAMP Control-Client is associated with zero or more TWAMP- 252 Control connections. The main configuration parameters of each 253 control connection are: 255 o A name which can be used to uniquely identify at the Control- 256 Client a particular control connection. This name is necessary 257 for programmability reasons because at the time of creation of a 258 TWAMP-Control connection not all IP and TCP port number 259 information needed to uniquely identify the connection is 260 available. 262 o The IP address of the interface the Control-Client will use for 263 connections. 265 o The IP address of the remote TWAMP Server. 267 o Authentication and encryption attributes such as KeyID, Token and 268 the Client Initialization Vector (Client-IV); see also the last 269 paragraph of Section 6 in [RFC4656] and [RFC4086]. 271 Each TWAMP-Control connection, in turn, is associated with zero or 272 more TWAMP-Test sessions. For each test session we note the 273 following configuration items: 275 o The test session name that uniquely identifies a particular test 276 session at the Control-Client and Session-Sender. Similarly to 277 the control connections above, this unique test session name is 278 needed because at the time of creation of a TWAMP-Test session, 279 for example, the source UDP port number is not known to uniquely 280 identify the test session. 282 o The IP address and UDP port number of the Session-Sender on the 283 path under test by TWAMP. 285 o The IP address and UDP port number of the Session-Reflector on 286 said path. 288 o Information pertaining to the test packet stream, such as the test 289 starting time, which performance metric is to be used 290 [I-D.ietf-ippm-metric-registry], or whether the test should be 291 repeated. 293 3.2. Server 295 Each TWAMP Server has an administrative status field set at the 296 device level to indicate whether the node is enabled to function as a 297 TWAMP Server. 299 Each Server is associated with zero or more TWAMP-Control 300 connections. Each control connection is uniquely identified by the 301 4-tuple {Control-Client IP address, Control-Client TCP port number, 302 Server IP address, Server TCP port}. Control connection configuration 303 items on a TWAMP Server are read-only. 305 3.3. Session-Sender 307 A TWAMP Session-Sender has an administrative status field set at the 308 device level that indicates whether the node is enabled to function 309 as such. 311 There is one Session-Sender instance for each TWAMP-Test session that 312 is initiated from the sending device. Primary configuration fields 313 include: 315 o The test session name that MUST be identical with the 316 corresponding test session name on the TWAMP Control-Client 317 (Section 3.1). 319 o The control connection name, which along with the test session 320 name uniquely identify the TWAMP Session-Sender instance. 322 o Information pertaining to the test packet stream, such as, for 323 example, the number of test packets and the packet distribution to 324 be employed; see also [RFC3432]. 326 3.4. Session-Reflector 328 Each TWAMP Session-Reflector has an administrative status field set 329 at the device level to indicate whether the node is enabled to 330 function as such. 332 Each Session-Reflector is associated with zero or more TWAMP-Test 333 sessions. For each test session, the REFWAIT timeout parameter which 334 determines whether to discontinue the session if no packets have been 335 received ([RFC5357], Section 4.2) can be configured. 337 Read-only access to other data model parameters, such as the Sender 338 IP address is foreseen. Each test session can be uniquely identified 339 by the 4-tuple mentioned in Section 3.2. 341 4. Data Model Parameters 343 This section defines the TWAMP data model using UML and introduces 344 selected parameters associated with the four TWAMP logical entities. 345 The complete TWAMP data model specification is provided in the YANG 346 module presented in Section 5.2. 348 4.1. Control-Client 350 The client container (see Figure 3) holds items that are related to 351 the configuration of the TWAMP Control-Client logical entity (recall 352 Figure 1). 354 The client container includes an administrative configuration 355 parameter (client/admin-state) that indicates whether the device is 356 allowed to initiate TWAMP-Control connections. 358 +-------------+ 359 | client | 360 +-------------+ 1..* +-----------------------+ 361 | admin-state |<>----------------------| mode-preference-chain | 362 | | +-----------------------+ 363 | | 1..* +------------+ | priority | 364 | |<>-----| key-chain | | mode | 365 +-------------+ +------------+ +-----------------------+ 366 ^ | key-id | 367 V | secret-key | 368 | +------------+ 369 | 0..* 370 +------------------------+ 371 | ctrl-connection | 372 +------------------------+ 373 | name | 374 | client-ip | 375 | server-ip | 376 | server-tcp-port | 0..* +----------------------+ 377 | control-packet-dscp |<>-------| test-session-request | 378 | key-id | +----------------------+ 379 | max-count | | name | 380 | client-tcp-port {ro} | | sender-ip | 381 | server-start-time {ro} | | sender-udp-port | 382 | state {ro} | | reflector-ip | 383 | selected-mode {ro} | | reflector-udp-port | 384 | token {ro} | | timeout | 385 | client-iv {ro} | | padding-length | 386 +------------------------+ | test-packet-dscp | 387 | start-time | 388 +-------------+ 1 | repeat | 389 | pm-reg-list |------<>| repeat-interval | 390 +-------------+ | state {ro} | 391 | pm-index | | sid {ro} | 392 +-------------+ +----------------------+ 394 Figure 3: TWAMP Control-Client UML class diagram 396 The client container holds a list (mode-preference-chain) which 397 specifies the Mode values according to their preferred order of use 398 by the operator of this Control-Client, including the authentication 399 and encryption Modes. Specifically, mode-preference-chain lists the 400 mode and its corresponding priority, expressed as a 16-bit unsigned 401 integer, where zero is the highest priority and subsequent values are 402 monotonically increasing. 404 Depending on the Modes available in the Server Greeting, the Control- 405 Client MUST choose the highest priority Mode from the configured 406 mode-preference-chain list. 408 Note that the list of preferred Modes may set bit position 409 combinations when necessary, such as when referring to the extended 410 TWAMP features in [RFC5618], [RFC5938], [RFC6038], and [RFC7717]. If 411 the Control-Client cannot determine an acceptable Mode, it MUST 412 respond with zero Mode bits set in the Set-up Response message, 413 indicating it will not continue with the control connection. 415 In addition, the client container holds a list named key-chain which 416 relates KeyIDs with the respective secret keys. Both the Server and 417 the Control-Client use the same mappings from KeyIDs to shared 418 secrets (key-id and secret-key in Figure 3, respectively). The 419 Server, being prepared to conduct sessions with more than one 420 Control-Client, uses KeyIDs to choose the appropriate secret-key; a 421 Control-Client would typically have different secret keys for 422 different Servers. The secret-key is the shared secret, an octet 423 string of arbitrary length whose interpretation as a text string is 424 unspecified. The key-id and secret-key encoding SHOULD follow 425 Section 9.4 of [RFC7950]. The derived key length (dkLen in 426 [RFC8018]) MUST be 16 octets for the AES Session-key used for 427 encryption and 32 octets for the HMAC-SHA1 Session-key used for 428 authentication; see also Section 6.10 of [RFC4656]. 430 Each client container also holds a list of control connections, where 431 each item in the list describes a TWAMP control connection initiated 432 by this Control-Client. There SHALL be one ctrl-connection per 433 TWAMP-Control (TCP) connection that is to be initiated from this 434 device. 436 In turn, each ctrl-connection holds a list of test-session-request. 437 test-session-request holds information associated with the Control- 438 Client for this test session. This includes information associated 439 with the Request-TW-Session/Accept-Session message exchange (see 440 Section 3.5 of [RFC5357]). 442 There SHALL be one instance of test-session-request for each TWAMP- 443 Test session that is to be negotiated by this TWAMP-Control 444 connection via a Request-TW-Session/Accept-Session exchange. 446 The Control-Client is also responsible for scheduling TWAMP-Test 447 sessions so test-session-request holds information related to these 448 actions (e.g. pm-index, repeat-interval). 450 4.2. Server 452 The server container (see Figure 4) holds items that are related to 453 the configuration of the TWAMP Server logical entity (recall 454 Figure 1). 456 The server container includes an administrative configuration 457 parameter (server/admin-state) that indicates whether the device is 458 allowed to receive TWAMP-Control connections. 460 A device operating in the Server role cannot configure attributes on 461 a per TWAMP-Control connection basis, as it has no foreknowledge of 462 the incoming TWAMP-Control connections to be received. Consequently, 463 any parameter that the Server might want to apply to an incoming 464 control connection must be configured at the overall Server level and 465 applied to all incoming TWAMP-Control connections. 467 +---------------------+ 468 | server | 469 +---------------------+ 470 | admin-state | 1..* +------------+ 471 | server-tcp-port |<>------| key-chain | 472 | servwait | +------------+ 473 | control-packet-dscp | | key-id | 474 | count | | secret-key | 475 | max-count | +------------+ 476 | modes | 477 | | 0..* +--------------------------+ 478 | |<>------| ctrl-connection | 479 +---------------------+ +--------------------------+ 480 | client-ip {ro} | 481 | client-tcp-port {ro} | 482 | server-ip {ro} | 483 | server-tcp-port {ro} | 484 | state {ro} | 485 | control-packet-dscp {ro} | 486 | selected-mode {ro} | 487 | key-id {ro} | 488 | count {ro} | 489 | max-count {ro} | 490 | salt {ro} | 491 | server-iv {ro} | 492 | challenge {ro} | 493 +--------------------------+ 495 Figure 4: TWAMP Server UML class diagram 497 Each server container holds a list named key-chain which relates 498 KeyIDs with the respective secret keys. As mentioned in Section 4.1, 499 both the Server and the Control-Client use the same mappings from 500 KeyIDs to shared secrets. The Server, being prepared to conduct 501 sessions with more than one Control-Client, uses KeyIDs to choose the 502 appropriate secret-key; a Control-Client would typically have 503 different secret keys for different Servers. key-id tells the Server 504 which shared-secret the Control-Client wishes to use for 505 authentication or encryption. 507 Each incoming control connection active on the Server is represented 508 by a ctrl-connection. There SHALL be one ctrl-connection per 509 incoming TWAMP-Control (TCP) connection that is received and active 510 on the Server. Each ctrl-connection can be uniquely identified by 511 the 4-tuple {client-ip, client-tcp-port, server-ip, server-tcp-port}. 512 All items in the ctrl-connection list are read-only. 514 4.3. Session-Sender 516 The session-sender container, illustrated in Figure 5, holds items 517 that are related to the configuration of the TWAMP Session-Sender 518 logical entity. 520 The session-sender container includes an administrative parameter 521 (session-sender/admin-state) that controls whether the device is 522 allowed to initiate TWAMP-Test sessions. 524 +----------------+ 525 | session-sender | 526 +----------------+ 0..* +---------------------------+ 527 | admin-state |<>-----| test-session | 528 +----------------+ +---------------------------+ 529 | name | 530 | ctrl-connection-name {ro} | 531 | fill-mode | 532 | number-of-packets | 533 | state {ro} | 534 | sent-packets {ro} | 535 | rcv-packets {ro} | 536 | last-sent-seq {ro} | 537 | last-rcv-seq {ro} | 538 +---------------------------+ 539 ^ 540 V 541 | 1 542 +---------------------+ 543 | packet-distribution | 544 +---------------------+ 545 | periodic / poisson | 546 +---------------------+ 547 | | 548 +-------------------+ | 549 | periodic-interval | | 550 +-------------------+ | 551 | 552 +--------------+ 553 | lambda | 554 | max-interval | 555 +--------------+ 557 Figure 5: TWAMP Session-Sender UML class diagram 559 Each TWAMP-Test session initiated by the Session-Sender will be 560 represented by an instance of a test-session object. There SHALL be 561 one instance of test-session for each TWAMP-Test session for which 562 packets are being sent. 564 4.4. Session-Reflector 566 The session-reflector container, illustrated in Figure 6, holds items 567 that are related to the configuration of the TWAMP Session-Reflector 568 logical entity. 570 The session-reflector container includes an administrative parameter 571 (session-reflector/admin-state) that controls whether the device is 572 allowed to respond to incoming TWAMP-Test sessions. 574 A device operating in the Session-Reflector role cannot configure 575 attributes on a per-session basis, as it has no foreknowledge of what 576 incoming sessions it will receive. As such, any parameter that the 577 Session-Reflector might want to apply to an incoming TWAMP-Test 578 session must be configured at the overall Session-Reflector level and 579 are applied to all incoming sessions. 581 +----=--------------+ 582 | session-reflector | 583 +-------------------+ 584 | admin-state | 585 | refwait | 586 +-------------------+ 587 ^ 588 V 589 | 590 | 0..* 591 +----------------------------------------+ 592 | test-session | 593 +----------------------------------------+ 594 | sid {ro} | 595 | sender-ip {ro} | 596 | sender-udp-port {ro} | 597 | reflector-ip {ro} | 598 | reflector-udp-port {ro} | 599 | parent-connection-client-ip {ro} | 600 | parent-connection-client-tcp-port {ro} | 601 | parent-connection-server-ip {ro} | 602 | parent-connection-server-tcp-port {ro} | 603 | test-packet-dscp {ro} | 604 | sent-packets {ro} | 605 | rcv-packets {ro} | 606 | last-sent-seq {ro} | 607 | last-rcv-seq {ro} | 608 +----------------------------------------+ 610 Figure 6: TWAMP Session-Reflector UML class diagram 612 Each incoming TWAMP-Test session that is active on the Session- 613 Reflector SHALL be represented by an instance of a test-session 614 object. All items in the test-session object are read-only. 616 Instances of test-session are indexed by a session identifier (sid). 617 This value is auto-allocated by the TWAMP Server as test session 618 requests are received, and communicated back to the Control-Client in 619 the SID field of the Accept-Session message; see Section 4.3 of 620 [RFC6038]. 622 When attempting to retrieve operational data for active test sessions 623 from a Session-Reflector device, the user will not know what sessions 624 are currently active on that device, or what SIDs have been auto- 625 allocated for these test sessions. If the user has network access to 626 the Control-Client device, then it is possible to read the data for 627 this session under client/ctrl-connection/test-session-request/sid 628 and obtain the SID (see Figure 3). The user may then use this SID 629 value as an index to retrieve an individual session-reflector/test- 630 session instance on the Session-Reflector device. 632 If the user has no network access to the Control-Client device, then 633 the only option is to retrieve all test-session instances from the 634 Session-Reflector device, and then pick out specific test-session 635 instances of interest to the user. This could be problematic if a 636 large number of test sessions are currently active on that device. 638 Each Session-Reflector TWAMP-Test session contains the following 639 4-tuple: {parent-connection-client-ip, parent-connection-client-tcp- 640 port, parent-connection-server-ip, parent-connection-server-tcp- 641 port}. This 4-tuple MUST correspond to the equivalent 4-tuple 642 {client-ip, client-tcp-port, server-ip, server-tcp-port} in server/ 643 ctrl-connection. This 4-tuple allows the user to trace back from the 644 TWAMP-Test session to the (parent) TWAMP-Control connection that 645 negotiated this test session. 647 5. Data Model 649 This section formally specifies the TWAMP data model using YANG. 651 5.1. YANG Tree Diagram 653 This section presents a simplified graphical representation of the 654 TWAMP data model using a YANG tree diagram. Readers should keep in 655 mind that the limit of 72 characters per line forces us to introduce 656 artificial line breaks in some tree diagram nodes. 658 module: ietf-twamp 659 +--rw twamp 660 +--rw client! {control-client}? 661 | +--rw admin-state boolean 662 | +--rw mode-preference-chain* [priority] 663 | | +--rw priority uint16 664 | | +--rw mode? twamp-modes 665 | +--rw key-chain* [key-id] 666 | | +--rw key-id string 667 | | +--rw secret-key? binary 668 | +--rw ctrl-connection* [name] 669 | +--rw name string 670 | +--rw client-ip? inet:ip-address 671 | +--rw server-ip inet:ip-address 672 | +--rw server-tcp-port? inet:port-number 673 | +--rw control-packet-dscp? inet:dscp 674 | +--rw key-id? string 675 | +--rw max-count? uint8 676 | +--ro client-tcp-port? inet:port-number 677 | +--ro server-start-time? uint64 678 | +--ro repeat-count? uint64 679 | +--ro state? 680 | | control-client-connection-state 681 | +--ro selected-mode? twamp-modes 682 | +--ro token? binary 683 | +--ro client-iv? binary 684 | +--rw test-session-request* [name] 685 | +--rw name string 686 | +--rw sender-ip? inet:ip-address 687 | +--rw sender-udp-port? union 688 | +--rw reflector-ip inet:ip-address 689 | +--rw reflector-udp-port? uint32 690 | +--rw timeout? uint64 691 | +--rw padding-length? uint32 692 | +--rw test-packet-dscp? inet:dscp 693 | +--rw start-time? uint64 694 | +--rw repeat? union 695 | +--rw repeat-interval? uint32 696 | +--rw pm-reg-list* [pm-index] 697 | | +--rw pm-index uint16 698 | +--ro state? test-session-state 699 | +--ro sid? string 700 +--rw server! {server}? 701 | +--rw admin-state boolean 702 | +--rw server-tcp-port? inet:port-number 703 | +--rw servwait? uint32 704 | +--rw control-packet-dscp? inet:dscp 705 | +--rw count? uint8 706 | +--rw max-count? uint8 707 | +--rw modes? twamp-modes 708 | +--rw key-chain* [key-id] 709 | | +--rw key-id string 710 | | +--rw secret-key? binary 711 | +--ro ctrl-connection* 712 | [client-ip client-tcp-port server-ip server-tcp-port] 713 | +--ro client-ip inet:ip-address 714 | +--ro client-tcp-port inet:port-number 715 | +--ro server-ip inet:ip-address 716 | +--ro server-tcp-port inet:port-number 717 | +--ro state? server-ctrl-connection-state 718 | +--ro control-packet-dscp? inet:dscp 719 | +--ro selected-mode? twamp-modes 720 | +--ro key-id? string 721 | +--ro count? uint8 722 | +--ro max-count? uint8 723 | +--ro salt? binary 724 | +--ro server-iv? binary 725 | +--ro challenge? binary 726 +--rw session-sender! {session-sender}? 727 | +--rw admin-state boolean 728 | +--rw test-session* [name] 729 | +--rw name string 730 | +--ro ctrl-connection-name? string 731 | +--rw fill-mode? padding-fill-mode 732 | +--rw number-of-packets uint32 733 | +--rw (packet-distribution)? 734 | | +--:(periodic) 735 | | | +--rw periodic-interval decimal64 736 | | +--:(poisson) 737 | | +--rw lambda decimal64 738 | | +--rw max-interval? decimal64 739 | +--ro state? sender-session-state 740 | +--ro sent-packets? uint32 741 | +--ro rcv-packets? uint32 742 | +--ro last-sent-seq? uint32 743 | +--ro last-rcv-seq? uint32 744 +--rw session-reflector! {session-reflector}? 745 +--rw admin-state boolean 746 +--rw refwait? uint32 747 +--ro test-session* 748 [sender-ip sender-udp-port reflector-ip reflector-udp 749 -port] 750 +--ro sid? string 751 +--ro sender-ip inet:ip-address 752 +--ro sender-udp-port 753 | dynamic-port-number 754 +--ro reflector-ip inet:ip-address 755 +--ro reflector-udp-port uint32 756 +--ro parent-connection-client-ip? inet:ip-address 757 +--ro parent-connection-client-tcp-port? inet:port-numbe 758 r 759 +--ro parent-connection-server-ip? inet:ip-address 760 +--ro parent-connection-server-tcp-port? inet:port-numbe 761 r 762 +--ro test-packet-dscp? inet:dscp 763 +--ro sent-packets? uint32 764 +--ro rcv-packets? uint32 765 +--ro last-sent-seq? uint32 766 +--ro last-rcv-seq? uint32 768 Figure 7: YANG Tree Diagram. 770 5.2. YANG Module 772 This section presents the YANG module for the TWAMP data model 773 defined in this document. The module imports definitions from Common 774 YANG Data Types [RFC6991]. 776 file "ietf-twamp@2018-04-08.yang" 778 module ietf-twamp { 779 yang-version 1.1; 780 namespace urn:ietf:params:xml:ns:yang:ietf-twamp; 781 prefix ietf-twamp; 783 import ietf-inet-types { 784 prefix inet; 785 reference 786 "RFC 6991: Common YANG Types."; 787 } 789 organization 790 "IETF IPPM (IP Performance Metrics) Working Group"; 792 contact 793 "WG Web: http://tools.ietf.org/wg/ippm/ 794 WG List: ippm@ietf.org 796 Editor: Ruth Civil 797 gcivil@ciena.com 798 Editor: Al Morton 799 acmorton@att.com 800 Editor: Reshad Rehman 801 rrahman@cisco.com 802 Editor: Mahesh Jethanandani 803 mjethanandani@gmail.com 804 Editor: Kostas Pentikousis 805 k.pentikousis@travelping.com"; 807 description 808 "This YANG module specifies a vendor-independent data 809 model for the Two-Way Active Measurement Protocol (TWAMP). 811 The data model covers four TWAMP logical entities, namely, 812 Control-Client, Server, Session-Sender, and Session-Reflector, 813 as illustrated in the annotated TWAMP logical model (Fig. 1 814 of RFC XXXX). 816 This YANG module uses features to indicate which of the four 817 logical entities are supported by a TWAMP implementation."; 819 revision 2018-04-08 { 820 description 821 "Initial Revision. 823 Covers RFC 5357, RFC 5618, RFC 5938, RFC 6038, RFC 7717, and 824 draft-ietf-ippm-metric-registry"; 826 reference 827 "RFC XXXX: TWAMP YANG Data Model."; 828 } 830 /* 831 * Typedefs 832 */ 834 typedef twamp-modes { 835 type bits { 836 bit unauthenticated { 837 position 0; 838 description 839 "Unauthenticated mode, in which no encryption or 840 authentication is applied in TWAMP-Control and 841 TWAMP-Test. KeyID, Token, and Client-IV are not used in 842 the Set-Up-Response message. See Section 3.1 of 843 RFC 4656."; 844 reference 845 "RFC 4656: A One-way Active Measurement Protocol 846 (OWAMP)"; 847 } 848 bit authenticated { 849 position 1; 850 description 851 "Authenticated mode, in which the Control-Client and 852 Server possess a shared secret thus prohibiting 853 'theft of service'. As per Section 6 of RFC 4656, 854 in 'authenticated mode, the timestamp is in the clear 855 and is not protected cryptographically in any way, 856 while the rest of the message has the same protection 857 as in encrypted mode. This mode allows one to trade off 858 cryptographic protection against accuracy of 859 timestamps.'"; 860 reference 861 "RFC 4656: A One-way Active Measurement Protocol 862 (OWAMP)"; 863 } 864 bit encrypted { 865 position 2; 866 description 867 "Encrypted mode 'makes it impossible to alter 868 timestamps undetectably.' See also Section 4 of RFC 7717 869 and Section 6 of RFC 4656."; 870 reference 871 "RFC 4656: A One-way Active Measurement Protocol 872 (OWAMP)"; 873 } 874 bit unauth-test-encrpyt-control { 875 position 3; 876 description 877 "When using the Mixed Security Mode, the TWAMP-Test 878 protocol follows the Unauthenticated mode and the 879 TWAMP-Control protocol the Encrypted mode."; 880 reference 881 "RFC 5618: Mixed Security Mode for the Two-Way Active 882 Measurement Protocol (TWAMP)"; 883 } 884 bit individual-session-control { 885 position 4; 886 description 887 "This mode enables individual test sessions using 888 Session Identifiers."; 889 reference 890 "RFC 5938: Individual Session Control Feature 891 for the Two-Way Active Measurement Protocol (TWAMP)"; 892 } 893 bit reflect-octets { 894 position 5; 895 description 896 "This mode indicates the reflect octets capability."; 897 reference 898 "RFC 6038: Two-Way Active Measurement Protocol (TWAMP) 899 Reflect Octets and Symmetrical Size Features"; 900 } 901 bit symmetrical-size { 902 position 6; 903 description 904 "This mode indicates support for the symmetrical size 905 sender test packet format."; 906 reference 907 "RFC 6038: Two-Way Active Measurement Protocol (TWAMP) 908 Reflect Octets and Symmetrical Size Features"; 909 } 910 bit IKEv2Derived { 911 position 7; 912 description 913 "In this mode the the shared key is derived 914 from an IKEv2 security association (SA)."; 915 reference 916 "RFC 7717: IKEv2-Derived Shared Secret Key for 917 the One-Way Active Measurement Protocol (OWAMP) 918 and Two-Way Active Measurement Protocol (TWAMP)"; 919 } 920 } 921 description 922 "Specifies the configurable TWAMP-Modes supported during a 923 TWAMP-Control Connection setup between a Control-Client 924 and a Server. Section 7 of RFC 7717 summarizes the 925 TWAMP-Modes registry and points to their formal 926 specification."; 927 } 929 typedef control-client-connection-state { 930 type enumeration { 931 enum active { 932 description 933 "Indicates an active TWAMP-Control connection to 934 Server."; 935 } 936 enum idle { 937 description 938 "Indicates an idle TWAMP-Control connection to Server."; 939 } 940 } 941 description 942 "Indicates the Control-Client TWAMP-Control connection 943 state."; 944 } 946 typedef test-session-state { 947 type enumeration { 948 enum accepted { 949 value 0; 950 description 951 "Indicates that accepted TWAMP-Test session request."; 953 } 954 enum failed { 955 value 1; 956 description 957 "Indicates a TWAMP-Test session failure due to 958 some unspecified reason (catch-all)."; 959 } 960 enum internal-error { 961 value 2; 962 description 963 "Indicates a TWAMP-Test session failure due to 964 an internal error."; 965 } 966 enum not-supported { 967 value 3; 968 description 969 "Indicates a TWAMP-Test session failure because 970 some aspect of the TWAMP-Test session request 971 is not supported."; 972 } 973 enum permanent-resource-limit { 974 value 4; 975 description 976 "Indicates a TWAMP-Test session failure due to 977 permanent resource limitations."; 978 } 979 enum temp-resource-limit { 980 value 5; 981 description 982 "Indicates a TWAMP-Test session failure due to 983 temporary resource limitations."; 984 } 985 } 986 description 987 "Indicates the Control-Client TWAMP-Test session state."; 988 } 990 typedef server-ctrl-connection-state { 991 type enumeration { 992 enum active { 993 description 994 "Indicates an active TWAMP-Control connection 995 to the Control-Client."; 996 } 997 enum servwait { 998 description 999 "Indicates that the TWAMP-Control connection to the 1000 Control-Client is in SERVWAIT as per the definition of 1001 Section 3.1 of RFC 5357."; 1002 } 1003 } 1004 description 1005 "Indicates the Server TWAMP-Control connection state."; 1006 } 1008 typedef sender-session-state { 1009 type enumeration { 1010 enum active { 1011 description 1012 "Indicates that the TWAMP-Test session is active."; 1013 } 1014 enum failure { 1015 description 1016 "Indicates that the TWAMP-Test session has failed."; 1017 } 1018 } 1019 description 1020 "Indicates the Session-Sender TWAMP-Test session state."; 1021 } 1023 typedef padding-fill-mode { 1024 type enumeration { 1025 enum zero { 1026 description 1027 "TWAMP-Test packets are padded with all zeros."; 1028 } 1029 enum random { 1030 description 1031 "TWAMP-Test packets are padded with pseudo-random 1032 numbers."; 1033 } 1034 } 1035 description 1036 "Indicates what type of packet padding is used in the 1037 TWAMP-Test packets."; 1038 } 1040 typedef dynamic-port-number { 1041 type inet:port-number { 1042 range 49152..65535; 1043 } 1044 description "Dynamic range for port numbers."; 1045 } 1047 /* 1048 * Features 1049 */ 1051 feature control-client { 1052 description 1053 "Indicates that the device supports configuration of the 1054 TWAMP Control-Client logical entity."; 1055 } 1057 feature server { 1058 description 1059 "Indicates that the device supports configuration of the 1060 TWAMP Server logical entity."; 1061 } 1063 feature session-sender { 1064 description 1065 "Indicates that the device supports configuration of the 1066 TWAMP Session-Sender logical entity."; 1067 } 1069 feature session-reflector { 1070 description 1071 "Indicates that the device supports configuration of the 1072 TWAMP Session-Reflector logical entity."; 1073 } 1075 /* 1076 * Reusable node groups 1077 */ 1079 grouping key-management { 1080 list key-chain { 1081 key key-id; 1082 leaf key-id { 1083 type string { 1084 length 1..80; 1085 } 1086 description 1087 "KeyID used for a TWAMP-Control connection. As per 1088 Section 3.1 of RFC 4656, KeyID is 'a UTF-8 string, up to 1089 80 octets in length' and is used to select which 'shared 1090 shared secret the [Control-Client] wishes to use to 1091 authenticate or encrypt'."; 1092 } 1093 leaf secret-key { 1094 type binary; 1095 description 1096 "The secret key corresponding to the KeyID for this 1097 TWAMP-Control connection."; 1098 } 1099 description 1100 "Relates KeyIDs with their respective secret keys 1101 in a TWAMP-Control connection."; 1102 } 1103 description 1104 "Used by the Control-Client and Server for TWAMP-Control 1105 key management."; 1106 } 1108 grouping maintenance-statistics { 1109 leaf sent-packets { 1110 type uint32; 1111 config false; 1112 description 1113 "Indicates the number of packets sent."; 1114 } 1116 leaf rcv-packets { 1117 type uint32; 1118 config false; 1119 description 1120 "Indicates the number of packets received."; 1121 } 1123 leaf last-sent-seq { 1124 type uint32; 1125 config false; 1126 description 1127 "Indicates the last sent sequence number."; 1128 } 1130 leaf last-rcv-seq { 1131 type uint32; 1132 config false; 1133 description 1134 "Indicates the last received sequence number."; 1135 } 1136 description 1137 "Used for TWAMP-Test maintenance statistics."; 1138 } 1140 grouping count { 1141 leaf count { 1142 type uint8 { 1143 range "10..31"; 1145 } 1146 default 10; 1147 description 1148 "Parameter communicated to the Control-Client as part of 1149 the Server Greeting message and used for deriving a key 1150 from a shared secret as per Section 3.1 of RFC 4656: 1151 MUST be a power of 2 and at least 1024. It is configured 1152 by providing said power. For example, configuring 15 here 1153 means count 2^15 = 32768. The default is 10, 1154 meaning 2^10 = 1024."; 1155 } 1156 description 1157 "Reusable data structure for count which is used both in the 1158 Server container."; 1159 } 1161 grouping max-count { 1162 leaf max-count { 1163 type uint8 { 1164 range 10..31; 1165 } 1166 default 15; 1167 description 1168 "This parameter limits the maximum Count value, which MUST 1169 be a power of 2 and at least 1024 as per RFC 5357. It is 1170 configured by providing said power. For example, 1171 configuring 10 here means max count 2^10 = 1024. 1172 The default is 15, meaning 2^15 = 32768. 1174 A TWAMP Server uses this configured value in the 1175 Server-Greeting message sent to the Control-Client. 1177 A TWAMP Control-Client uses this configured value to 1178 prevent denial-of-service (DOS) attacks by closing the 1179 control connection to the Server if it 'receives a 1180 Server-Greeting message with Count greater that its 1181 maximum configured value', as per Section 6 of RFC 5357. 1183 Further, note that according to Section 6 of RFC 5357: 1185 'If an attacking system sets the maximum value in 1186 Count (2**32), then the system under attack would stall 1187 for a significant period of time while it attempts to 1188 generate keys. 1190 TWAMP-compliant systems SHOULD have a configuration 1191 control to limit the maximum count value. The default 1192 max-count value SHOULD be 32768.' 1193 RFC 5357 does not qualify 'significant period' in terms of 1194 time, but it is clear that this depends on the processing 1195 capacity available and operators need to pay attention to 1196 this security consideration."; 1197 } 1198 description 1199 "Reusable data structure for max-count which is used both at 1200 the Control-Client and the Server containers."; 1201 } 1203 /* 1204 * Configuration data nodes 1205 */ 1207 container twamp { 1208 description 1209 "TWAMP logical entity configuration grouping of four models 1210 which correspond to the four TWAMP logical entities 1211 Control-Client, Server, Session-Sender, and Session-Reflector 1212 as illustrated in Fig. 1 of RFC XXXX."; 1214 container client { 1215 if-feature control-client; 1216 presence "Enables TWAMP Control-Client functionality."; 1217 description 1218 "Configuration of the TWAMP Control-Client logical 1219 entity."; 1221 leaf admin-state { 1222 type boolean; 1223 mandatory true; 1224 description 1225 "Indicates whether the device is allowed to operate as a 1226 TWAMP Control-Client."; 1227 } 1229 list mode-preference-chain { 1230 key priority; 1231 unique mode; 1232 leaf priority { 1233 type uint16; 1234 description 1235 "Indicates the Control-Client Mode preference priority 1236 expressed as a 16-bit unsigned integer, where zero is 1237 the highest priority and subsequent values 1238 monotonically increasing."; 1239 } 1240 leaf mode { 1241 type twamp-modes; 1242 description 1243 "The supported TWAMP Mode matching the corresponding 1244 priority."; 1246 } 1247 description 1248 "Indicates the Control-Client preferred order of use of 1249 the supported TWAMP Modes. 1251 Depending on the Modes available in the TWAMP Server 1252 Greeting message (see Fig. 2 of RFC 7717), the 1253 this Control-Client MUST choose the highest priority 1254 Mode from the configured mode-preference-chain list."; 1255 } 1257 uses key-management; 1259 list ctrl-connection { 1260 key name; 1261 description 1262 "List of TWAMP Control-Client control connections. 1263 Each item in the list describes a control connection 1264 that will be initiated by this Control-Client"; 1266 leaf name { 1267 type string; 1268 description 1269 "A unique name used as a key to identify this 1270 individual TWAMP-Control connection on the 1271 Control-Client device."; 1272 } 1273 leaf client-ip { 1274 type inet:ip-address; 1275 description 1276 "The IP address of the local Control-Client device, 1277 to be placed in the source IP address field of the 1278 IP header in TWAMP-Control (TCP) packets belonging 1279 to this control connection. If not configured, the 1280 device SHALL choose its own source IP address."; 1281 } 1282 leaf server-ip { 1283 type inet:ip-address; 1284 mandatory true; 1285 description 1286 "The IP address of the remote Server device, which the 1287 TWAMP-Control connection will be initiated to."; 1289 } 1291 leaf server-tcp-port { 1292 type inet:port-number; 1293 default 862; 1294 description 1295 "This parameter defines the TCP port number that is 1296 to be used by this outgoing TWAMP-Control connection. 1297 Typically, this is the well-known TWAMP-Control 1298 port number (862) as per RFC 5357 However, there are 1299 known realizations of TWAMP in the field that were 1300 implemented before this well-known port number was 1301 allocated. These early implementations allowed the 1302 port number to be configured. This parameter is 1303 therefore provided for backward compatibility 1304 reasons."; 1305 } 1307 leaf control-packet-dscp { 1308 type inet:dscp; 1309 default 0; 1310 description 1311 "The DSCP value to be placed in the IP header of 1312 TWAMP-Control (TCP) packets generated by this 1313 Control-Client."; 1314 } 1316 leaf key-id { 1317 type string { 1318 length 1..80; 1319 } 1320 description 1321 "Indicates the KeyID value selected for this 1322 TWAMP-Control connection."; 1323 } 1325 uses max-count; 1327 leaf client-tcp-port { 1328 type inet:port-number; 1329 config false; 1330 description 1331 "Indicates the source TCP port number used in the 1332 TWAMP-Control packets belonging to this control 1333 connection."; 1334 } 1336 leaf server-start-time { 1337 type uint64; 1338 config false; 1339 description 1340 "Indicates the Start-Time advertized by the Server in 1341 the Server-Start message (RFC 4656, Section 3.1), 1342 representing the time when the current 1343 instantiation of the Server started operating. 1344 The timestamp format follows RFC 1305 1345 according to Section 4.1.2 of RFC 4656."; 1346 } 1348 leaf repeat-count { 1349 type uint64; 1350 config false; 1351 description 1352 "Indicates how many times the test session has been 1353 repeated. When a test is running, this value will be 1354 greater than 0. If the repeat parameter is non-zero, 1355 this value is smaller than or equal to the repeat 1356 parameter."; 1357 } 1358 leaf state { 1359 type control-client-connection-state; 1360 config false; 1361 description 1362 "Indicates the current state of the TWAMP-Control 1363 connection state."; 1364 } 1366 leaf selected-mode { 1367 type twamp-modes; 1368 config false; 1369 description 1370 "The TWAMP Mode that the Control-Client has chosen for 1371 this control connection as set in the Mode field of 1372 the Set-Up-Response message"; 1373 reference 1374 "RFC 4656, Section 3.1."; 1375 } 1377 leaf token { 1378 type binary { 1379 length 64; 1380 } 1381 config false; 1382 description 1383 "This parameter holds the 64 octets containing the 1384 concatenation of a 16-octet Challenge, a 16-octet AES 1385 Session-key used for encryption, and a 32-octet 1386 HMAC-SHA1 Session-key used for authentication; see 1387 also the last paragraph of Section 6 in RFC 4656. 1389 If the Mode defined in RFC 7717 is selected 1390 (selected-mode), Token is limited to 16 octets."; 1391 reference 1392 "RFC 4086: Randomness Requirements for Security 1394 RFC 7717: IKEv2-Derived Shared Secret Key for the 1395 One-Way Active Measurement Protocol (OWAMP) and 1396 Two-Way Active Measurement Protocol (TWAMP)"; 1397 } 1399 leaf client-iv { 1400 type binary { 1401 length 16; 1402 } 1403 config false; 1404 description 1405 "Indicates the Control-Client Initialization Vector 1406 (Client-IV), that is generated randomly by the 1407 Control-Client. As per RFC 4656: 1409 Client-IV merely needs to be unique (i.e., it MUST 1410 never be repeated for different sessions using the 1411 same secret key; a simple way to achieve that without 1412 the use of cumbersome state is to generate the 1413 Client-IV values using a cryptographically secure 1414 pseudo-random number source. 1416 If the Mode defined in RFC 7717 is selected 1417 (selected-mode), Client-IV is limited to 12 octets."; 1418 reference 1419 "RFC 4656: A One-way Active Measurement Protocol 1420 (OWAMP). 1422 RFC 7717: IKEv2-Derived Shared Secret Key for the 1423 One-Way Active Measurement Protocol (OWAMP) and 1424 Two-Way Active Measurement Protocol (TWAMP)"; 1425 } 1427 list test-session-request { 1428 key name; 1429 description 1430 "Information associated with the Control-Client 1431 for this test session"; 1433 leaf name { 1434 type string; 1435 description 1436 "A unique name to be used for identification of 1437 this TWAMP-Test session on the Control-Client."; 1438 } 1440 leaf sender-ip { 1441 type inet:ip-address; 1442 description 1443 "The IP address of the Session-Sender device, 1444 which is to be placed in the source IP address 1445 field of the IP header in TWAMP-Test (UDP) packets 1446 belonging to this test session. This value will be 1447 used to populate the sender address field of the 1448 Request-TW-Session message. 1450 If not configured, the device SHALL choose its own 1451 source IP address."; 1452 } 1454 leaf sender-udp-port { 1455 type union { 1456 type dynamic-port-number; 1457 type enumeration { 1458 enum autoallocate { 1459 description 1460 "Indicates that the Contol-Client will 1461 auto-allocate the TWAMP-Test (UDP) port number 1462 from the dynamic port range."; 1463 } 1464 } 1465 } 1466 default autoallocate; 1467 description 1468 "The UDP port number that is to be used by 1469 the Session-Sender for this TWAMP-Test session. 1470 The number is restricted to the dynamic port range. 1472 By default the Control-Client SHALL auto-allocate a 1473 UDP port number for this TWAMP-Test session. 1475 The configured (or auto-allocated) value is 1476 advertized in the Sender Port field of the 1477 Request-TW-session message (see Section 3.5 of 1478 RFC 5357). Note that in the scenario where a device 1479 auto-allocates a UDP port number for a session, and 1480 the repeat parameter for that session indicates that 1481 it should be repeated, the device is free to 1482 auto-allocate a different UDP port number when it 1483 negotiates the next (repeated) iteration of this 1484 session."; 1485 } 1487 leaf reflector-ip { 1488 type inet:ip-address; 1489 mandatory true; 1490 description 1491 "The IP address belonging to the remote 1492 Session-Reflector device to which the TWAMP-Test 1493 session will be initiated. This value will be 1494 used to populate the receiver address field of 1495 the Request-TW-Session message."; 1496 } 1498 leaf reflector-udp-port { 1499 type uint32 { 1500 range "862 | 49152..65535"; 1501 } 1502 description 1503 "This parameter defines the UDP port number that 1504 will be used by the Session-Reflector for 1505 this TWAMP-Test session. The default number is 1506 within to the dynamic port range and is to be placed 1507 in the Receiver Port field of the Request-TW-Session 1508 message. The new well-known port (862) MAY be 1509 used."; 1510 } 1512 leaf timeout { 1513 type uint64; 1514 units seconds; 1515 default 2; 1516 description 1517 "The length of time (in seconds) that the 1518 Session-Reflector should continue to respond to 1519 packets belonging to this TWAMP-Test session after 1520 a Stop-Sessions TWAMP-Control message has been 1521 received (RFC 5357, Section 3.8). 1523 This value will be placed in the Timeout field of 1524 the Request-TW-Session message."; 1525 } 1527 leaf padding-length { 1528 type uint32 { 1529 range 64..4096; 1530 } 1531 description 1532 "The number of padding bytes to be added to the 1533 TWAMP-Test (UDP) packets generated by the 1534 Session-Sender. 1536 This value will be placed in the Padding Length 1537 field of the Request-TW-Session message."; 1538 reference 1539 "RFC 4656, Section 3.5."; 1540 } 1542 leaf test-packet-dscp { 1543 type inet:dscp; 1544 default 0; 1545 description 1546 "The DSCP value to be placed in the IP header 1547 of TWAMP-Test packets generated by the 1548 Session-Sender, and in the UDP header of the 1549 TWAMP-Test response packets generated by the 1550 Session-Reflector for this test session. 1552 This value will be placed in the Type-P Descriptor 1553 field of the Request-TW-Session message"; 1554 reference 1555 "RFC 5357."; 1556 } 1558 leaf start-time { 1559 type uint64; 1560 default 0; 1561 description 1562 "Time when the session is to be started 1563 (but not before the TWAMP Start-Sessions command 1564 is issued; see Section 3.4 of RFC 5357). 1566 The start-time value is placed in the Start Time 1567 field of the Request-TW-Session message. 1569 The timestamp format follows RFC 1305 as per 1570 Section 3.5 of RFC 4656. 1572 The default value of 0 indicates that the session 1573 will be started as soon as the Start-Sessions 1574 message is received."; 1575 } 1576 leaf repeat { 1577 type union { 1578 type uint32 { 1579 range 0..4294967294; 1580 } 1581 type enumeration { 1582 enum forever { 1583 description 1584 "Indicates that the test session SHALL be 1585 repeated *forever* using the information in 1586 repeat-interval parameter, and SHALL NOT 1587 decrement the value."; 1588 } 1589 } 1590 } 1591 default 0; 1592 description 1593 "This value determines if the TWAMP-Test session must 1594 be repeated. When a test session has completed, the 1595 repeat parameter is checked. 1597 The default value of 0 indicates that the session 1598 MUST NOT be repeated. 1600 If the repeat value is 1 through 4,294,967,294 1601 then the test session SHALL be repeated using the 1602 information in repeat-interval parameter, and the 1603 parent TWAMP-Control connection for this test 1604 session is restarted to negotiate a new instance 1605 of this TWAMP-Test session."; 1606 } 1608 leaf repeat-interval { 1609 when "../repeat!='0'" { 1610 description 1611 "This parameter determines the timing of repeated 1612 TWAMP-Test sessions when repeat is more than 0. 1614 When the value of repeat-interval is 0, the 1615 negotiation of a new test session SHALL begin 1616 immediately after the previous test session 1617 completes. Otherwise, the Control-Client will 1618 wait for the number of seconds specified in the 1619 repeat-interval parameter before negotiating the 1620 new instance of this TWAMP-Test session."; 1621 } 1622 type uint32; 1623 units seconds; 1624 default 0; 1625 description 1626 "Repeat interval (in seconds)."; 1627 } 1629 list pm-reg-list { 1630 key pm-index; 1631 leaf pm-index { 1632 type uint16; 1633 description 1634 "Numerical index value of a Registered Metric 1635 in the Performance Metric Registry 1636 (see ietf-ippm-metric-registry). Output statistics 1637 are specified in the corresponding Registry 1638 entry."; 1639 } 1640 description 1641 "A list of one or more Performance Metric Registry 1642 Index values, which communicate packet stream 1643 characteristics along with one or more metrics 1644 to be measured. 1646 All members of the pm-reg-list MUST have the same 1647 stream characteristics, such that they combine 1648 to specify all metrics that shall be measured on 1649 a single stream."; 1650 reference 1651 "ietf-ippm-metric-registry: Registry for 1652 Performance Metrics"; 1653 } 1655 leaf state { 1656 type test-session-state; 1657 config false; 1658 description 1659 "Indicates the TWAMP-Test session state, accepted or 1660 indication of an error."; 1661 reference 1662 "Section 3.5 of RFC 5357."; 1663 } 1664 leaf sid { 1665 type string; 1666 config false; 1667 description 1668 "The SID allocated by the Server for this TWAMP-Test 1669 session, and communicated back to the Control-Client 1670 in the SID field of the Accept-Session message"; 1671 reference 1672 "Section 4.3 of RFC 6038."; 1673 } 1674 } 1675 } 1676 } 1678 container server { 1679 if-feature server; 1680 presence "Enables TWAMP Server functionality."; 1681 description 1682 "Configuration of the TWAMP Server logical entity."; 1684 leaf admin-state { 1685 type boolean; 1686 mandatory true; 1687 description 1688 "Indicates whether the device is allowed to operate 1689 as a TWAMP Server."; 1690 } 1692 leaf server-tcp-port { 1693 type inet:port-number; 1694 default 862; 1695 description 1696 "This parameter defines the well known TCP port number 1697 that is used by TWAMP-Control. The Server will listen 1698 on this port number for incoming TWAMP-Control 1699 connections. Although this is defined as a fixed value 1700 (862) in RFC 5357, there are several realizations of 1701 TWAMP in the field that were implemented before this 1702 well-known port number was allocated. These early 1703 implementations allowed the port number to be 1704 configured. This parameter is therefore provided for 1705 backward compatibility reasons."; 1706 } 1708 leaf servwait { 1709 type uint32 { 1710 range 1..604800; 1711 } 1712 units seconds; 1713 default 900; 1714 description 1715 "TWAMP-Control (TCP) session timeout, in seconds. 1716 According to Section 3.1 of RFC 5357, 1718 Server MAY discontinue any established control 1719 connection when no packet associated with that 1720 connection has been received within SERVWAIT seconds."; 1721 } 1723 leaf control-packet-dscp { 1724 type inet:dscp; 1725 description 1726 "The DSCP value to be placed in the IP header of 1727 TWAMP-Control (TCP) packets generated by the Server. 1729 Section 3.1 of RFC 5357 specifies that the server 1730 SHOULD use the DSCP value from the Control-Clients 1731 TCP SYN. However, for practical purposes TWAMP will 1732 typically be implemented using a general purpose TCP 1733 stack provided by the underlying operating system, 1734 and such a stack may not provide this information to the 1735 user. Consequently, it is not always possible to 1736 implement the behavior described in RFC 5357 in an 1737 OS-portable version of TWAMP. 1739 The default behavior if this item is not set is to use 1740 the DSCP value from the Control-Clients TCP SYN."; 1741 reference 1742 "Section 3.1 of RFC 5357."; 1743 } 1745 uses count; 1747 uses max-count; 1749 leaf modes { 1750 type twamp-modes; 1751 description 1752 "The bit mask of TWAMP Modes this Server instance 1753 is willing to support; see IANA TWAMP Modes Registry."; 1754 } 1756 uses key-management; 1758 list ctrl-connection { 1759 key "client-ip client-tcp-port server-ip server-tcp-port"; 1760 config false; 1761 description 1762 "List of all incoming TWAMP-Control (TCP) connections."; 1764 leaf client-ip { 1765 type inet:ip-address; 1766 description 1767 "The IP address on the remote Control-Client device, 1768 which is the source IP address used in the 1769 TWAMP-Control (TCP) packets belonging to this control 1770 connection."; 1771 } 1773 leaf client-tcp-port { 1774 type inet:port-number; 1775 description 1776 "The source TCP port number used in the TWAMP-Control 1777 (TCP) packets belonging to this control connection."; 1778 } 1780 leaf server-ip { 1781 type inet:ip-address; 1782 description 1783 "The IP address of the local Server device, which is 1784 the destination IP address used in the 1785 TWAMP-Control (TCP) packets belonging to this control 1786 connection."; 1787 } 1789 leaf server-tcp-port { 1790 type inet:port-number; 1791 description 1792 "The destination TCP port number used in the 1793 TWAMP-Control (TCP) packets belonging to this 1794 control connection. This will usually be the 1795 same value as the server-tcp-port configured 1796 under twamp/server. However, in the event that 1797 the user re-configured server/server-tcp-port 1798 after this control connection was initiated, this 1799 value will indicate the server-tcp-port that is 1800 actually in use for this control connection."; 1801 } 1803 leaf state { 1804 type server-ctrl-connection-state; 1805 description 1806 "Indicates the Server TWAMP-Control connection state."; 1807 } 1809 leaf control-packet-dscp { 1810 type inet:dscp; 1811 description 1812 "The DSCP value used in the IP header of the 1813 TWAMP-Control (TCP) packets sent by the Server 1814 for this control connection. This will usually 1815 be the same value as is configured in the 1816 control-packet-dscp parameter under the twamp/server 1817 container. However, in the event that the user 1818 re-configures server/dscp after this control 1819 connection is already in progress, this read-only 1820 value will show the actual dscp value in use by this 1821 TWAMP-Control connection."; 1822 } 1824 leaf selected-mode { 1825 type twamp-modes; 1826 description 1827 "The Mode that was chosen for this TWAMP-Control 1828 connection as set in the Mode field of the 1829 Set-Up-Response message."; 1830 } 1832 leaf key-id { 1833 type string { 1834 length 1..80; 1835 } 1836 description 1837 "The KeyID value that is in use by this TWAMP-Control 1838 connection as selected by Control-Client."; 1839 } 1841 uses count { 1842 description 1843 "The count value that is in use by this TWAMP-Control 1844 connection. This will usually be the same value 1845 as is configured under twamp/server. However, in the 1846 event that the user re-configured server/count 1847 after this control connection is already in progress, 1848 this read-only value will show the actual count that 1849 is in use for this TWAMP-Control connection."; 1850 } 1852 uses max-count { 1853 description 1854 "This read-only value indicates the actual max-count in 1855 use for this control connection. Usually this would be 1856 the same value as configured under twamp/server."; 1857 } 1859 leaf salt { 1860 type binary { 1861 length 16; 1862 } 1863 description 1864 "A parameter used in deriving a key from a 1865 shared secret as described in Section 3.1 of RFC 4656. 1866 It is communicated to the Control-Client as part of 1867 the Server Greeting message."; 1868 } 1870 leaf server-iv { 1871 type binary { 1872 length 16; 1873 } 1874 description 1875 "The Server Initialization Vector 1876 (IV) generated randomly by the Server."; 1877 } 1879 leaf challenge { 1880 type binary { 1881 length 16; 1882 } 1883 description 1884 "A random sequence of octets generated by the Server. 1885 As described in client/token, Challenge is used 1886 by the Control-Client to prove possession of a 1887 shared secret."; 1888 } 1889 } 1890 } 1892 container session-sender { 1893 if-feature session-sender; 1894 presence "Enables TWAMP Session-Sender functionality."; 1895 description 1896 "Configuration of the TWAMP Session-Sender logical entity"; 1897 leaf admin-state { 1898 type boolean; 1899 mandatory true; 1900 description 1901 "Indicates whether the device is allowed to operate 1902 as a TWAMP Session-Sender."; 1903 } 1905 list test-session{ 1906 key name; 1907 description 1908 "List of TWAMP Session-Sender test sessions."; 1910 leaf name { 1911 type string; 1912 description 1913 "A unique name for this TWAMP-Test session to be used 1914 for identifying this test session by the 1915 Session-Sender logical entity."; 1916 } 1918 leaf ctrl-connection-name { 1919 type string; 1920 config false; 1921 description 1922 "The name of the parent TWAMP-Control connection that 1923 is responsible for negotiating this TWAMP-Test 1924 session."; 1925 } 1927 leaf fill-mode { 1928 type padding-fill-mode; 1929 default zero; 1930 description 1931 "Indicates whether the padding added to the 1932 TWAMP-Test (UDP) packets will contain pseudo-random 1933 numbers, or whether it should consist of all zeroes, 1934 as per Section 4.2.1 of RFC 5357."; 1935 } 1937 leaf number-of-packets { 1938 type uint32; 1939 mandatory true; 1940 description 1941 "The overall number of TWAMP-Test (UDP) packets to be 1942 transmitted by the Session-Sender for this test 1943 session."; 1944 } 1946 choice packet-distribution { 1947 description 1948 "Indicates the distribution to be used for transmitting 1949 the TWAMP-Test (UDP) packets."; 1950 case periodic { 1951 leaf periodic-interval { 1952 type decimal64 { 1953 fraction-digits 5; 1954 } 1955 units seconds; 1956 mandatory true; 1957 description 1958 "Indicates the time to wait (in seconds) between 1959 the first bits of TWAMP-Test (UDP) packet 1960 transmissions for this test session."; 1961 reference 1962 "RFC 3432: Network performance measurement 1963 with periodic streams"; 1964 } 1965 } 1966 case poisson { 1967 leaf lambda { 1968 type decimal64 { 1969 fraction-digits 5; 1970 } 1971 units seconds; 1972 mandatory true; 1973 description 1974 "Indicates the average time interval (in seconds) 1975 between packets in the Poisson distribution. 1976 The packet is calculated using the reciprocal of 1977 lambda and the TWAMP-Test packet size (which 1978 depends on the selected Mode and the packet 1979 padding)."; 1980 reference 1981 "RFC 2330: Framework for IP Performance Metrics"; 1982 } 1983 leaf max-interval { 1984 type decimal64 { 1985 fraction-digits 5; 1986 } 1987 units seconds; 1988 description 1989 "Indicates the maximum time (in seconds) 1990 between packet transmissions."; 1991 reference 1992 "RFC 7312: Advanced Stream and Sampling Framework 1993 for IP Performance Metrics (IPPM)"; 1994 } 1995 } 1996 } 1998 leaf state { 1999 type sender-session-state; 2000 config false; 2001 description 2002 "Indicates the Session-Sender test session state."; 2003 } 2005 uses maintenance-statistics; 2006 } 2007 } 2008 container session-reflector { 2009 if-feature session-reflector; 2010 presence "Enables TWAMP Session-Reflector functionality."; 2011 description 2012 "Configuration of the TWAMP Session-Reflector logical 2013 entity"; 2015 leaf admin-state { 2016 type boolean; 2017 mandatory true; 2018 description 2019 "Indicates whether the device is allowed to operate 2020 as a TWAMP Session-Reflector."; 2021 } 2023 leaf refwait { 2024 type uint32 { 2025 range 1..604800; 2026 } 2027 units seconds; 2028 default 900; 2029 description 2030 "The Session-Reflector MAY discontinue any session that 2031 has been started when no packet associated with that 2032 session has been received for REFWAIT seconds. As per 2033 Section 3.1 of RFC 5357, this timeout allows a 2034 Session-Reflector to free up resources in case of 2035 failure."; 2036 } 2038 list test-session { 2039 key 2040 "sender-ip sender-udp-port 2041 reflector-ip reflector-udp-port"; 2042 config false; 2043 description 2044 "TWAMP Session-Reflectortest sessions."; 2046 leaf sid { 2047 type string; 2048 description 2049 "An auto-allocated identifier for this TWAMP-Test 2050 session that is unique within the context of this 2051 Server/Session-Reflector device only. This value 2052 is communicated to the Control-Client that 2053 requested the test session in the SID field of the 2054 Accept-Session message."; 2055 } 2056 leaf sender-ip { 2057 type inet:ip-address; 2058 description 2059 "The IP address on the remote device, which is the 2060 source IP address used in the TWAMP-Test (UDP) packets 2061 belonging to this test session."; 2062 } 2064 leaf sender-udp-port { 2065 type dynamic-port-number; 2066 description 2067 "The source UDP port used in the TWAMP-Test packets 2068 belonging to this test session."; 2069 } 2071 leaf reflector-ip { 2072 type inet:ip-address; 2073 description 2074 "The IP address of the local Session-Reflector 2075 device, which is the destination IP address used 2076 in the TWAMP-Test (UDP) packets belonging to this test 2077 session."; 2078 } 2080 leaf reflector-udp-port { 2081 type uint32 { 2082 range "862 | 49152..65535"; 2083 } 2084 description 2085 "The destination UDP port number used in the 2086 TWAMP-Test (UDP) test packets belonging to this 2087 test session."; 2088 } 2090 leaf parent-connection-client-ip { 2091 type inet:ip-address; 2092 description 2093 "The IP address on the Control-Client device, which 2094 is the source IP address used in the TWAMP-Control 2095 (TCP) packets belonging to the parent control 2096 connection that negotiated this test session."; 2097 } 2099 leaf parent-connection-client-tcp-port { 2100 type inet:port-number; 2101 description 2102 "The source TCP port number used in the TWAMP-Control 2103 (TCP) packets belonging to the parent control 2104 connection that negotiated this test session."; 2105 } 2107 leaf parent-connection-server-ip { 2108 type inet:ip-address; 2109 description 2110 "The IP address of the Server device, which is the 2111 destination IP address used in the TWAMP-Control 2112 (TCP) packets belonging to the parent control 2113 connection that negotiated this test session."; 2114 } 2116 leaf parent-connection-server-tcp-port { 2117 type inet:port-number; 2118 description 2119 "The destination TCP port number used in the 2120 TWAMP-Control (TCP) packets belonging to the parent 2121 control connection that negotiated this test 2122 session."; 2123 } 2125 leaf test-packet-dscp { 2126 type inet:dscp; 2127 description 2128 "The DSCP value present in the IP header of 2129 TWAMP-Test (UDP) packets belonging to this session."; 2130 } 2132 uses maintenance-statistics; 2133 } 2134 } 2135 } 2136 } 2138 2140 6. Data Model Examples 2142 This section presents a simple but complete example of configuring 2143 all four entities in Figure 1, based on the YANG module specified in 2144 Section 5. The example is illustrative in nature, but aims to be 2145 self-contained, i.e. were it to be executed in a real TWAMP 2146 implementation it would lead to a correctly configured test session. 2147 For completeness, examples are provided for both IPv4 and IPv6. 2149 A more elaborated example, which also includes authentication 2150 parameters, is provided in Appendix A. 2152 6.1. Control-Client 2154 Figure 8 shows a configuration example for a Control-Client with 2155 client/admin-state enabled. In a real implementation following 2156 Figure 2 this would permit the initiation of TWAMP-Control 2157 connections and TWAMP-Test sessions. 2159 [note: '\' line wrapping is for formatting only] 2161 2162 2163 2164 2165 true 2166 2167 2168 2170 Figure 8: XML instance enabling Control-Client operation. 2172 The following example shows a Control-Client with two instances of 2173 client/ctrl-connection, one called "RouterA" and another called 2174 "RouterB". Each TWAMP-Control connection is to a different Server. 2175 The control connection named "RouterA" has two test session requests. 2176 The TWAMP-Control connection named "RouterB" has no TWAMP-Test 2177 session requests. 2179 [note: '\' line wrapping is for formatting only] 2181 2182 2183 2184 2185 true 2186 2187 RouterA 2188 203.0.113.1 2189 203.0.113.2 2190 2191 Test1 2192 203.0.113.3 2193 54001 2194 203.0.113.4 2195 50001 2196 0 2197 2198 2199 Test2 2200 203.0.113.1 2201 54001 2202 203.0.113.2 2203 50001 2204 0 2205 2206 2207 2208 RouterB 2209 203.0.113.1 2210 203.0.113.3 2211 2212 2213 2214 2216 [note: '\' line wrapping is for formatting only] 2218 2219 2220 2221 2222 true 2223 2224 RouterA 2225 2001:DB8:203:0:113::1 2226 2001:DB8:203:0:113::2 2227 2228 Test1 2229 2001:DB8:203:1:113::3 2230 54000 2231 2001:DB8:203:1:113::4 2232 55000 2233 0 2234 2235 2236 Test2 2237 2001:DB8:203:0:113::1 2238 54001 2239 2001:DB8:203:0:113::2 2240 55001 2241 0 2242 2243 2244 2245 RouterB 2246 2001:DB8:203:0:113::1 2247 2001:DB8:203:0:113::3 2248 2249 2250 2251 2253 6.2. Server 2255 Figure 9 shows a configuration example for a Server with server/ 2256 admin-state enabled, which permits a device following Figure 2 to 2257 respond to TWAMP-Control connections and TWAMP-Test sessions. 2259 [note: '\' line wrapping is for formatting only] 2261 2262 2263 2264 2265 true 2266 2267 2268 2270 Figure 9: XML instance enabling Server operation. 2272 The following example presents a Server with the TWAMP-Control 2273 connection corresponding to the control connection name (client/ctrl- 2274 connection/name) "RouterA" presented in Section 6.1. 2276 [note: '\' line wrapping is for formatting only] 2278 2279 2280 2281 2282 true 2283 2284 203.0.113.1 2285 16341 2286 203.0.113.2 2287 862 2288 active 2289 2290 2291 2292 2294 [note: '\' line wrapping is for formatting only] 2296 2297 2298 2299 2300 true 2301 2302 2001:DB8:203:0:113::1 2303 16341 2304 2001:DB8:203:0:113::2 2305 862 2306 active 2307 2308 2309 2310 2312 6.3. Session-Sender 2314 Figure 10 shows a configuration example for a Session-Sender with 2315 session-sender/admin-state enabled, which permits a device following 2316 Figure 2 to initiate TWAMP-Test sessions. 2318 [note: '\' line wrapping is for formatting only] 2320 2321 2322 2323 2324 true 2325 2326 2327 2329 Figure 10: XML instance enabling Session-Sender operation. 2331 The following configuration example shows a Session-Sender with the 2332 two TWAMP-Test sessions presented in Section 6.1. 2334 [note: '\' line wrapping is for formatting only] 2336 2337 2338 2339 2340 true 2341 2342 Test1 2343 RouterA 2344 900 2345 1 2346 2347 2348 Test2 2349 RouterA 2350 900 2351 1 2352 2 2353 2354 2355 2356 2358 6.4. Session-Reflector 2360 This configuration example shows a Session-Reflector with session- 2361 reflector/admin-state enabled, which permits a device following 2362 Figure 2 to respond to TWAMP-Test sessions. 2364 [note: '\' line wrapping is for formatting only] 2366 2367 2368 2369 2370 true 2371 2372 2373 2375 Figure 11: XML instance enabling Session-Reflector operation. 2377 The following example shows the two Session-Reflector TWAMP-Test 2378 sessions corresponding to the test sessions presented in Section 6.3. 2380 [note: '\' line wrapping is for formatting only] 2382 2383 2384 2385 2386 true 2387 2388 203.0.113.3 2389 54000 2390 203.0.113.4 2391 50001 2392 1232 2393 203.0.113.1 2395 16341 2397 203.0.113.2 2399 862 2401 2 2402 2 2403 1 2404 1 2405 2406 2407 203.0.113.1 2408 54001 2409 192.68.0.2 2410 50001 2411 178943 2412 203.0.113.1 2414 16341 2416 203.0.113.2 2418 862 2420 21 2421 21 2422 20 2423 20 2424 2425 2426 2427 2429 [note: '\' line wrapping is for formatting only] 2431 2432 2433 2434 2435 true 2436 2437 203.0.113.3 2438 54000 2439 203.0.113.4 2440 54001 2441 1232 2442 203.0.113.1 2444 16341 2446 203.0.113.2 2448 862 2450 2 2451 2 2452 1 2453 1 2454 2455 2456 203.0.113.1 2457 54001 2458 192.68.0.2 2459 55001 2460 178943 2461 203.0.113.1 2463 16341 2465 203.0.113.2 2467 862 2469 21 2470 21 2471 20 2472 20 2473 2474 2475 2476 2478 7. Security Considerations 2480 The YANG module defined in Section 5 is designed to be accessed, 2481 among other protocols, via NETCONF [RFC6241]. Protocols like NETCONF 2482 use a secure transport layer like SSH that is mandatory to implement. 2483 The NETCONF Access Control Module (NACM) [RFC8341] provides the means 2484 to restrict access for particular users to a pre-configured set of 2485 NETCONF protocol operations and attributes. 2487 There are a number of nodes defined in this YANG module which are 2488 writeable. These data nodes may be considered sensitive and 2489 vulnerable to attacks in some network environments. Ability to write 2490 into these nodes without proper protection can have a negative effect 2491 on the devices that support this feature. 2493 Examples of nodes that are particularly vulnerable include several 2494 timeout values put in the protocol to protect against sessions that 2495 are not active but are consuming resources. 2497 8. IANA Considerations 2499 This document registers a URI in the IETF XML registry [RFC3688]. 2500 Following the format in [RFC3688], the following registration is 2501 requested to be made. 2503 URI: urn:ietf:params:xml:ns:yang:ietf-twamp 2505 Registrant Contact: The IPPM WG of the IETF. 2507 XML: N/A, the requested URI is an XML namespace. 2509 This document registers a YANG module in the YANG Module Names 2510 registry [RFC6020]. 2512 name: ietf-twamp 2514 namespace: urn:ietf:params:xml:ns:yang:ietf-twamp 2516 prefix: twamp 2518 reference: RFC XXXX 2520 9. Acknowledgements 2522 We thank Fred Baker, Kevin D'Souza, Gregory Mirsky, Brian Trammell, 2523 Robert Sherman, and Marius Georgescu for their thorough and 2524 constructive reviews, comments and text suggestions. 2526 Haoxing Shen contributed to the definition of the YANG module in 2527 Section 5. 2529 Jan Lindblad and Ladislav Lhokta did thorough reviews of the YANG 2530 module and the examples in Appendix A. 2532 Kostas Pentikousis was partially supported by FP7 UNIFY 2533 (http://fp7-unify.eu), a research project partially funded by the 2534 European Community under the Seventh Framework Program (grant 2535 agreement no. 619609). The views expressed here are those of the 2536 authors only. The European Commission is not liable for any use that 2537 may be made of the information in this document. 2539 10. Contributors 2541 Lianshu Zheng. 2543 11. References 2545 11.1. Normative References 2547 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2548 Requirement Levels", BCP 14, RFC 2119, 2549 DOI 10.17487/RFC2119, March 1997, 2550 . 2552 [RFC3432] Raisanen, V., Grotefeld, G., and A. Morton, "Network 2553 performance measurement with periodic streams", RFC 3432, 2554 DOI 10.17487/RFC3432, November 2002, 2555 . 2557 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2558 DOI 10.17487/RFC3688, January 2004, 2559 . 2561 [RFC4656] Shalunov, S., Teitelbaum, B., Karp, A., Boote, J., and M. 2562 Zekauskas, "A One-way Active Measurement Protocol 2563 (OWAMP)", RFC 4656, DOI 10.17487/RFC4656, September 2006, 2564 . 2566 [RFC5357] Hedayat, K., Krzanowski, R., Morton, A., Yum, K., and J. 2567 Babiarz, "A Two-Way Active Measurement Protocol (TWAMP)", 2568 RFC 5357, DOI 10.17487/RFC5357, October 2008, 2569 . 2571 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2572 the Network Configuration Protocol (NETCONF)", RFC 6020, 2573 DOI 10.17487/RFC6020, October 2010, 2574 . 2576 [RFC6038] Morton, A. and L. Ciavattone, "Two-Way Active Measurement 2577 Protocol (TWAMP) Reflect Octets and Symmetrical Size 2578 Features", RFC 6038, DOI 10.17487/RFC6038, October 2010, 2579 . 2581 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 2582 RFC 6991, DOI 10.17487/RFC6991, July 2013, 2583 . 2585 [RFC7717] Pentikousis, K., Ed., Zhang, E., and Y. Cui, 2586 "IKEv2-Derived Shared Secret Key for the One-Way Active 2587 Measurement Protocol (OWAMP) and Two-Way Active 2588 Measurement Protocol (TWAMP)", RFC 7717, 2589 DOI 10.17487/RFC7717, December 2015, 2590 . 2592 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2593 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2594 . 2596 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2597 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2598 May 2017, . 2600 11.2. Informative References 2602 [I-D.ietf-ippm-metric-registry] 2603 Bagnulo, M., Claise, B., Eardley, P., Morton, A., and A. 2604 Akhter, "Registry for Performance Metrics", draft-ietf- 2605 ippm-metric-registry-14 (work in progress), March 2018. 2607 [I-D.unify-nfvrg-challenges] 2608 Szabo, R., Csaszar, A., Pentikousis, K., Kind, M., Daino, 2609 D., Qiang, Z., and H. Woesner, "Unifying Carrier and Cloud 2610 Networks: Problem Statement and Challenges", draft-unify- 2611 nfvrg-challenges-04 (work in progress), July 2016. 2613 [I-D.unify-nfvrg-devops] 2614 Meirosu, C., Manzalini, A., Steinert, R., Marchetto, G., 2615 Pentikousis, K., Wright, S., Lynch, P., and W. John, 2616 "DevOps for Software-Defined Telecom Infrastructures", 2617 draft-unify-nfvrg-devops-06 (work in progress), July 2016. 2619 [NSC] John, W., Pentikousis, K., et al., "Research directions in 2620 network service chaining", Proc. SDN for Future Networks 2621 and Services (SDN4FNS), Trento, Italy IEEE, November 2013. 2623 [RFC4086] Eastlake 3rd, D., Schiller, J., and S. Crocker, 2624 "Randomness Requirements for Security", BCP 106, RFC 4086, 2625 DOI 10.17487/RFC4086, June 2005, 2626 . 2628 [RFC5618] Morton, A. and K. Hedayat, "Mixed Security Mode for the 2629 Two-Way Active Measurement Protocol (TWAMP)", RFC 5618, 2630 DOI 10.17487/RFC5618, August 2009, 2631 . 2633 [RFC5938] Morton, A. and M. Chiba, "Individual Session Control 2634 Feature for the Two-Way Active Measurement Protocol 2635 (TWAMP)", RFC 5938, DOI 10.17487/RFC5938, August 2010, 2636 . 2638 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2639 and A. Bierman, Ed., "Network Configuration Protocol 2640 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2641 . 2643 [RFC7426] Haleplidis, E., Ed., Pentikousis, K., Ed., Denazis, S., 2644 Hadi Salim, J., Meyer, D., and O. Koufopavlou, "Software- 2645 Defined Networking (SDN): Layers and Architecture 2646 Terminology", RFC 7426, DOI 10.17487/RFC7426, January 2647 2015, . 2649 [RFC8018] Moriarty, K., Ed., Kaliski, B., and A. Rusch, "PKCS #5: 2650 Password-Based Cryptography Specification Version 2.1", 2651 RFC 8018, DOI 10.17487/RFC8018, January 2017, 2652 . 2654 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2655 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2656 . 2658 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 2659 Access Control Model", STD 91, RFC 8341, 2660 DOI 10.17487/RFC8341, March 2018, 2661 . 2663 Appendix A. Detailed Data Model Examples 2665 This appendix extends the example presented in Section 6 by 2666 configuring more fields such as authentication parameters, DSCP 2667 values and so on. 2669 A.1. Control-Client 2671 [note: '\' line wrapping is for formatting only] 2673 2674 2675 2676 2677 true 2678 2679 0 2680 authenticated 2681 2682 2683 1 2684 unauthenticated 2685 2686 2687 KeyClient1ToRouterA 2688 c2VjcmV0MQ== 2689 2690 2691 KeyForRouterB 2692 c2VjcmV0Mg0K 2693 2694 2695 RouterA 2696 203.0.113.1 2697 203.0.113.2 2698 32 2699 KeyClient1ToRouterA 2700 2701 Test1 2702 203.0.113.3 2703 54000 2704 203.0.113.4 2705 55000 2706 64 2707 0 2708 2709 2710 Test2 2711 203.0.113.1 2712 54001 2713 203.0.113.2 2714 55001 2715 128 2716 0 2717 2718 2719 2720 2721 2723 [note: '\' line wrapping is for formatting only] 2725 2726 2727 2728 2729 true 2730 2731 0 2732 authenticated 2733 2734 2735 1 2736 unauthenticated 2737 2738 2739 KeyClient1ToRouterA 2740 c2VjcmV0MQ== 2741 2742 2743 KeyForRouterB 2744 c2VjcmV0Mg0K 2746 2747 2748 RouterA 2749 2001:DB8:203:0:113::1 2750 2001:DB8:203:0:113::2 2751 32 2752 KeyClient1ToRouterA 2753 2754 Test1 2755 2001:DB8:10:1:1::1 2756 54000 2757 2001:DB8:10:1:1::2 2758 55000 2759 64 2760 0 2761 2762 2763 Test2 2764 2001:DB8:203:0:113::1 2765 54001 2766 2001:DB8:203:0:113::2 2767 55001 2768 128 2769 0 2770 2771 2772 2773 2774 2776 A.2. Server 2778 [note: '\' line wrapping is for formatting only] 2780 2781 2782 2783 2784 true 2785 1800 2786 32 2787 authenticated unauthenticated 2788 30 2789 2790 KeyClient1ToRouterA 2791 c2VjcmV0MQ== 2792 2793 2794 KeyClient10ToRouterA 2795 c2VjcmV0MTANCg== 2796 2797 2798 203.0.113.1 2799 16341 2800 203.0.113.2 2801 862 2802 32 2803 unauthenticated 2804 KeyClient1ToRouterA 2805 30 2806 2807 2808 2809 2811 [note: '\' line wrapping is for formatting only] 2813 2814 2815 2816 2817 true 2818 1800 2819 32 2820 authenticated unauthenticated 2821 30 2822 2823 KeyClient1ToRouterA 2824 c2VjcmV0MQ== 2825 2826 2827 KeyClient10ToRouterA 2828 c2VjcmV0MTANCg== 2829 2830 2831 2001:DB8:203:0:113::1 2832 16341 2833 2001:DB8:203:0:113::2 2834 862 2835 32 2836 unauthenticated 2837 KeyClient1ToRouterA 2838 30 2839 2840 2842 2843 2845 A.3. Session-Sender 2847 [note: '\' line wrapping is for formatting only] 2849 2850 2851 2852 2853 true 2854 2855 Test1 2856 RouterA 2857 zero 2858 900 2859 1 2860 2 2861 2 2862 1 2863 1 2864 2865 2866 Test2 2867 RouterA 2868 random 2869 900 2870 1 2871 2 2872 21 2873 21 2874 20 2875 20 2876 2877 2878 2879 2881 A.4. Session-Reflector 2883 [note: '\' line wrapping is for formatting only] 2885 2886 2887 2888 2889 true 2890 2891 203.0.113.3 2892 54000 2893 203.0.113.4 2894 55000 2895 1232 2896 203.0.113.1 2898 16341 2900 203.0.113.2 2902 862 2904 32 2905 2 2906 2 2907 1 2908 1 2909 2910 2911 203.0.113.1 2912 54001 2913 192.68.0.2 2914 55001 2915 178943 2916 203.0.113.1 2918 16341 2920 203.0.113.2 2922 862 2924 32 2925 21 2926 21 2927 20 2928 20 2929 2930 2931 2932 2934 [note: '\' line wrapping is for formatting only] 2935 2936 2937 2938 2939 true 2940 2941 2001:DB8:10:1:1::1 2942 54000 2943 2001:DB8:10:1:1::2 2944 55000 2945 1232 2946 2001:DB8:203:0:113::1 2948 16341 2950 2001:DB8:203:0:113::2 2952 862 2954 32 2955 2 2956 2 2957 1 2958 1 2959 2960 2961 2001:DB8:203:0:113::1 2962 54001 2963 2001:DB8:192:68::2 2964 55001 2965 178943 2966 2001:DB8:203:0:113::1 2968 16341 2970 2001:DB8:203:0:113::2 2972 862 2974 32 2975 21 2976 21 2977 20 2978 20 2979 2980 2981 2982 2984 Appendix B. TWAMP Operational Commands 2986 TWAMP operational commands could be performed programmatically or 2987 manually, e.g. using a command-line interface (CLI). 2989 With respect to programmability, YANG can be used to define NETCONF 2990 Remote Procedure Calls (RPC), therefore it would be, in principle, 2991 possible to define TWAMP RPC operations for actions such as starting 2992 or stopping control connections or test sessions or groups of 2993 sessions; retrieving results; clearing stored results, and so on. 2995 However, [RFC5357] does not attempt to describe such operational 2996 actions. Refer also to Section 2 and the unlabeled links in 2997 Figure 1. In actual deployments different TWAMP implementations may 2998 support different sets of operational commands, with different 2999 restrictions. Therefore, this document considers it the 3000 responsibility of the individual implementation to define its 3001 corresponding TWAMP operational commands data model. 3003 Authors' Addresses 3005 Ruth Civil 3006 Ciena Corporation 3007 307 Legget Drive 3008 Kanata, ON K2K 3C8 3009 Canada 3011 Email: gcivil@ciena.com 3012 URI: www.ciena.com 3014 Al Morton 3015 AT&T Labs 3016 200 Laurel Avenue South 3017 Middletown,, NJ 07748 3018 USA 3020 Phone: +1 732 420 1571 3021 Fax: +1 732 368 1192 3022 Email: acmorton@att.com 3023 Reshad Rahman 3024 Cisco Systems 3025 2000 Innovation Drive 3026 Kanata, ON K2K 3E8 3027 Canada 3029 Email: rrahman@cisco.com 3031 Mahesh Jethanandani 3033 Email: mjethanandani@gmail.com 3035 Kostas Pentikousis (editor) 3036 Travelping 3037 Siemensdamm 50 3038 Berlin 13629 3039 Germany 3041 Email: k.pentikousis@travelping.com