--- 1/draft-ietf-ippm-twamp-yang-06.txt 2018-04-08 15:13:13.886573185 -0700 +++ 2/draft-ietf-ippm-twamp-yang-07.txt 2018-04-08 15:13:14.006576071 -0700 @@ -1,25 +1,25 @@ IPPM WG R. Civil Internet-Draft Ciena Corporation Intended status: Standards Track A. Morton -Expires: August 17, 2018 AT&T Labs +Expires: October 10, 2018 AT&T Labs R. Rahman Cisco Systems M. Jethanandani K. Pentikousis, Ed. Travelping - February 13, 2018 + April 8, 2018 Two-Way Active Measurement Protocol (TWAMP) Data Model - draft-ietf-ippm-twamp-yang-06 + draft-ietf-ippm-twamp-yang-07 Abstract This document specifies a data model for client and server implementations of the Two-Way Active Measurement Protocol (TWAMP). We define the TWAMP data model through Unified Modeling Language (UML) class diagrams and formally specify it using YANG. Status of This Memo @@ -29,21 +29,21 @@ Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." - This Internet-Draft will expire on August 17, 2018. + This Internet-Draft will expire on October 10, 2018. Copyright Notice Copyright (c) 2018 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents @@ -67,85 +67,88 @@ 3.4. Session-Reflector . . . . . . . . . . . . . . . . . . . . 7 4. Data Model Parameters . . . . . . . . . . . . . . . . . . . . 8 4.1. Control-Client . . . . . . . . . . . . . . . . . . . . . 8 4.2. Server . . . . . . . . . . . . . . . . . . . . . . . . . 11 4.3. Session-Sender . . . . . . . . . . . . . . . . . . . . . 12 4.4. Session-Reflector . . . . . . . . . . . . . . . . . . . . 13 5. Data Model . . . . . . . . . . . . . . . . . . . . . . . . . 15 5.1. YANG Tree Diagram . . . . . . . . . . . . . . . . . . . . 15 5.2. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 18 6. Data Model Examples . . . . . . . . . . . . . . . . . . . . . 46 - 6.1. Control-Client . . . . . . . . . . . . . . . . . . . . . 46 - 6.2. Server . . . . . . . . . . . . . . . . . . . . . . . . . 48 - 6.3. Session-Sender . . . . . . . . . . . . . . . . . . . . . 49 - 6.4. Session-Reflector . . . . . . . . . . . . . . . . . . . . 50 - 7. Security Considerations . . . . . . . . . . . . . . . . . . . 53 + 6.1. Control-Client . . . . . . . . . . . . . . . . . . . . . 47 + 6.2. Server . . . . . . . . . . . . . . . . . . . . . . . . . 49 + 6.3. Session-Sender . . . . . . . . . . . . . . . . . . . . . 50 + 6.4. Session-Reflector . . . . . . . . . . . . . . . . . . . . 51 + 7. Security Considerations . . . . . . . . . . . . . . . . . . . 54 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 54 - 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 54 - 10. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 54 + 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 55 + 10. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 55 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 55 11.1. Normative References . . . . . . . . . . . . . . . . . . 55 - 11.2. Informative References . . . . . . . . . . . . . . . . . 56 - Appendix A. Detailed Data Model Examples . . . . . . . . . . . . 57 - A.1. Control-Client . . . . . . . . . . . . . . . . . . . . . 57 - A.2. Server . . . . . . . . . . . . . . . . . . . . . . . . . 59 - A.3. Session-Sender . . . . . . . . . . . . . . . . . . . . . 61 + 11.2. Informative References . . . . . . . . . . . . . . . . . 57 + Appendix A. Detailed Data Model Examples . . . . . . . . . . . . 58 + A.1. Control-Client . . . . . . . . . . . . . . . . . . . . . 58 + A.2. Server . . . . . . . . . . . . . . . . . . . . . . . . . 60 + A.3. Session-Sender . . . . . . . . . . . . . . . . . . . . . 62 A.4. Session-Reflector . . . . . . . . . . . . . . . . . . . . 62 - Appendix B. TWAMP Operational Commands . . . . . . . . . . . . . 64 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 64 + Appendix B. TWAMP Operational Commands . . . . . . . . . . . . . 65 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 65 1. Introduction The Two-Way Active Measurement Protocol (TWAMP) [RFC5357] is used to measure network performance parameters such as latency, bandwidth, and packet loss by sending probe packets and measuring their experience in the network. To date, TWAMP implementations do not - come with a standard management framework and, as such, configuration - depends on proprietary mechanisms developed by the corresponding - TWAMP vendor. This document addresses this gap by formally - specifying the TWAMP data model using YANG. + come with a standard management framework, and, as such, implementors + have no choice except to provide a proprietary mechanism. This + document addresses this gap by formally specifying the TWAMP data + model using YANG. 1.1. Motivation In current TWAMP deployments the lack of a standardized data model limits the flexibility to dynamically instantiate TWAMP-based measurements across equipment from different vendors. In large, virtualized, and dynamically instantiated infrastructures where network functions are placed according to orchestration algorithms as discussed in [I-D.unify-nfvrg-challenges][I-D.unify-nfvrg-devops], proprietary mechanisms for managing TWAMP measurements pose severe limitations with respect to programmability. Two major trends call for standardizing TWAMP management aspects. First, we expect that in the coming years large-scale and multi- vendor TWAMP deployments will become the norm. From an operations - perspective, dealing with several vendor-specific TWAMP configuration - mechanisms is simply unsustainable in this context. Second, the - increasingly software-defined and virtualized nature of network - infrastructures, based on dynamic service chains [NSC] and - programmable control and management planes [RFC7426] requires a well- - defined data model for TWAMP implementations. This document defines - such a TWAMP data model and specifies it formally using the YANG data - modeling language [RFC6020]. + perspective, using several vendor-specific TWAMP configuration + mechanisms when one standard mechanism could provide an alternative + is expensive and inefficient. Second, the increasingly software- + defined and virtualized nature of network infrastructures, based on + dynamic service chains [NSC] and programmable control and management + planes [RFC7426] requires a well-defined data model for TWAMP + implementations. This document defines such a TWAMP data model and + specifies it formally using the YANG data modeling language + [RFC7950]. Note to RFC Editor: - Please replace the date in the draft of the format 2018-02-13 with - the date of publication of this draft. Also, replace reference to - draft-ietf-ippm-twamp-yang, and draft-ietf-ippm-metric-registry with - the RFC numbers assigned to the draft. + Please replace the date 2018-04-08 in Section 5.2 of the draft with + the date of publication of this draft as a RFC. Also, replace + reference to RFC XXXX, and draft-ietf-ippm-metric-registry with the + RFC numbers assigned to the draft. 1.2. Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", - "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this - document are to be interpreted as described in [RFC2119]. + "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and + "OPTIONAL" in this document are to be interpreted as described in BCP + 14 [RFC2119] [RFC8174] when, and only when, they appear in all + capitals, as shown here. 1.3. Document Organization The rest of this document is organized as follows. Section 2 presents the scope and applicability of this document. Section 3 provides a high-level overview of the TWAMP data model. Section 4 details the configuration parameters of the data model and Section 5 specifies in YANG the TWAMP data model. Section 6 lists illustrative examples which conform to the YANG data model specified in this document. Appendix A elaborates these examples further. @@ -412,22 +415,22 @@ In addition, the client container holds a list named key-chain which relates KeyIDs with the respective secret keys. Both the Server and the Control-Client use the same mappings from KeyIDs to shared secrets (key-id and secret-key in Figure 3, respectively). The Server, being prepared to conduct sessions with more than one Control-Client, uses KeyIDs to choose the appropriate secret-key; a Control-Client would typically have different secret keys for different Servers. The secret-key is the shared secret, an octet string of arbitrary length whose interpretation as a text string is unspecified. The key-id and secret-key encoding SHOULD follow - Section 9.4 of [RFC6020]. The derived key length (dkLen in - [RFC2898]) MUST be 16 octets for the AES Session-key used for + Section 9.4 of [RFC7950]. The derived key length (dkLen in + [RFC8018]) MUST be 16 octets for the AES Session-key used for encryption and 32 octets for the HMAC-SHA1 Session-key used for authentication; see also Section 6.10 of [RFC4656]. Each client container also holds a list of control connections, where each item in the list describes a TWAMP control connection initiated by this Control-Client. There SHALL be one ctrl-connection per TWAMP-Control (TCP) connection that is to be initiated from this device. In turn, each ctrl-connection holds a list of test-session-request. @@ -621,22 +624,23 @@ are currently active on that device, or what SIDs have been auto- allocated for these test sessions. If the user has network access to the Control-Client device, then it is possible to read the data for this session under client/ctrl-connection/test-session-request/sid and obtain the SID (see Figure 3). The user may then use this SID value as an index to retrieve an individual session-reflector/test- session instance on the Session-Reflector device. If the user has no network access to the Control-Client device, then the only option is to retrieve all test-session instances from the - Session-Reflector device. This could be problematic if a large - number of test sessions are currently active on that device. + Session-Reflector device, and then pick out specific test-session + instances of interest to the user. This could be problematic if a + large number of test sessions are currently active on that device. Each Session-Reflector TWAMP-Test session contains the following 4-tuple: {parent-connection-client-ip, parent-connection-client-tcp- port, parent-connection-server-ip, parent-connection-server-tcp- port}. This 4-tuple MUST correspond to the equivalent 4-tuple {client-ip, client-tcp-port, server-ip, server-tcp-port} in server/ ctrl-connection. This 4-tuple allows the user to trace back from the TWAMP-Test session to the (parent) TWAMP-Control connection that negotiated this test session. @@ -759,102 +763,120 @@ +--ro sent-packets? uint32 +--ro rcv-packets? uint32 +--ro last-sent-seq? uint32 +--ro last-rcv-seq? uint32 Figure 7: YANG Tree Diagram. 5.2. YANG Module This section presents the YANG module for the TWAMP data model - defined in this document. + defined in this document. The module imports definitions from Common + YANG Data Types [RFC6991]. - file "ietf-twamp@2018-02-13.yang" + file "ietf-twamp@2018-04-08.yang" module ietf-twamp { - namespace - urn:ietf:params:xml:ns:yang:ietf-twamp; - - prefix - ietf-twamp; + yang-version 1.1; + namespace urn:ietf:params:xml:ns:yang:ietf-twamp; + prefix ietf-twamp; import ietf-inet-types { prefix inet; + reference + "RFC 6991: Common YANG Types."; } organization "IETF IPPM (IP Performance Metrics) Working Group"; contact - draft-ietf-ippm-twamp-yang@tools.ietf.org; + "WG Web: http://tools.ietf.org/wg/ippm/ + WG List: ippm@ietf.org + + Editor: Ruth Civil + gcivil@ciena.com + Editor: Al Morton + acmorton@att.com + Editor: Reshad Rehman + rrahman@cisco.com + Editor: Mahesh Jethanandani + mjethanandani@gmail.com + Editor: Kostas Pentikousis + k.pentikousis@travelping.com"; description "This YANG module specifies a vendor-independent data model for the Two-Way Active Measurement Protocol (TWAMP). The data model covers four TWAMP logical entities, namely, Control-Client, Server, Session-Sender, and Session-Reflector, as illustrated in the annotated TWAMP logical model (Fig. 1 - of draft-ietf-ippm-twamp-yang). + of RFC XXXX). This YANG module uses features to indicate which of the four logical entities are supported by a TWAMP implementation."; - revision 2018-02-13 { + revision 2018-04-08 { description "Initial Revision. Covers RFC 5357, RFC 5618, RFC 5938, RFC 6038, RFC 7717, and draft-ietf-ippm-metric-registry"; reference - draft-ietf-ippm-twamp-yang; + "RFC XXXX: TWAMP YANG Data Model."; } /* * Typedefs */ typedef twamp-modes { type bits { bit unauthenticated { position 0; description "Unauthenticated mode, in which no encryption or - authentication is applied in TWAMP-Control and TWAMP-Test. - KeyID, Token, and Client-IV are not used in the - Set-Up-Response message. See Section 3.1 of RFC 4656."; + authentication is applied in TWAMP-Control and + TWAMP-Test. KeyID, Token, and Client-IV are not used in + the Set-Up-Response message. See Section 3.1 of + RFC 4656."; reference - "RFC 4656: A One-way Active Measurement Protocol (OWAMP)"; + "RFC 4656: A One-way Active Measurement Protocol + (OWAMP)"; } bit authenticated { position 1; description - "Authenticated mode, in which the Control-Client and Server - possess a shared secret thus prohibiting 'theft of service'. - As per Section 6 of RFC 4656, in 'authenticated mode, the - timestamp is in the clear and is not protected - cryptographically in any way, while the rest of the message - has the same protection as in encrypted mode. This mode - allows one to trade off cryptographic protection against - accuracy of timestamps.'"; + "Authenticated mode, in which the Control-Client and + Server possess a shared secret thus prohibiting + 'theft of service'. As per Section 6 of RFC 4656, + in 'authenticated mode, the timestamp is in the clear + and is not protected cryptographically in any way, + while the rest of the message has the same protection + as in encrypted mode. This mode allows one to trade off + cryptographic protection against accuracy of + timestamps.'"; reference - "RFC 4656: A One-way Active Measurement Protocol (OWAMP)"; + "RFC 4656: A One-way Active Measurement Protocol + (OWAMP)"; } bit encrypted { position 2; description "Encrypted mode 'makes it impossible to alter timestamps undetectably.' See also Section 4 of RFC 7717 and Section 6 of RFC 4656."; reference - "RFC 4656: A One-way Active Measurement Protocol (OWAMP)"; + "RFC 4656: A One-way Active Measurement Protocol + (OWAMP)"; } bit unauth-test-encrpyt-control { position 3; description "When using the Mixed Security Mode, the TWAMP-Test protocol follows the Unauthenticated mode and the TWAMP-Control protocol the Encrypted mode."; reference "RFC 5618: Mixed Security Mode for the Two-Way Active Measurement Protocol (TWAMP)"; @@ -901,37 +923,40 @@ TWAMP-Control Connection setup between a Control-Client and a Server. Section 7 of RFC 7717 summarizes the TWAMP-Modes registry and points to their formal specification."; } typedef control-client-connection-state { type enumeration { enum active { description - "Indicates an active TWAMP-Control connection to Server."; + "Indicates an active TWAMP-Control connection to + Server."; } enum idle { description "Indicates an idle TWAMP-Control connection to Server."; } } description - "Indicates the Control-Client TWAMP-Control connection state."; + "Indicates the Control-Client TWAMP-Control connection + state."; } typedef test-session-state { type enumeration { enum accepted { value 0; description "Indicates that accepted TWAMP-Test session request."; + } enum failed { value 1; description "Indicates a TWAMP-Test session failure due to some unspecified reason (catch-all)."; } enum internal-error { value 2; description @@ -1108,30 +1134,31 @@ "Indicates the last received sequence number."; } description "Used for TWAMP-Test maintenance statistics."; } grouping count { leaf count { type uint8 { range "10..31"; + } default 10; description - "Parameter communicated to the Control-Client as part of the - Server Greeting message and used for deriving a key from a - shared secret as per Section 3.1 of RFC 4656: MUST be a - power of 2 and at least 1024. It is configured by providing - said power. For example, configuring 15 here means count - 2^15 = 32768. The default is 10, meaning 2^10 = 1024."; - + "Parameter communicated to the Control-Client as part of + the Server Greeting message and used for deriving a key + from a shared secret as per Section 3.1 of RFC 4656: + MUST be a power of 2 and at least 1024. It is configured + by providing said power. For example, configuring 15 here + means count 2^15 = 32768. The default is 10, + meaning 2^10 = 1024."; } description "Reusable data structure for count which is used both in the Server container."; } grouping max-count { leaf max-count { type uint8 { range 10..31; @@ -1140,25 +1167,25 @@ description "This parameter limits the maximum Count value, which MUST be a power of 2 and at least 1024 as per RFC 5357. It is configured by providing said power. For example, configuring 10 here means max count 2^10 = 1024. The default is 15, meaning 2^15 = 32768. A TWAMP Server uses this configured value in the Server-Greeting message sent to the Control-Client. - A TWAMP Control-Client uses this configured value to prevent - denial-of-service (DOS) attacks by closing the control - connection to the Server if it 'receives a Server-Greeting - message with Count greater that its maximum configured value', - as per Section 6 of RFC 5357. + A TWAMP Control-Client uses this configured value to + prevent denial-of-service (DOS) attacks by closing the + control connection to the Server if it 'receives a + Server-Greeting message with Count greater that its + maximum configured value', as per Section 6 of RFC 5357. Further, note that according to Section 6 of RFC 5357: 'If an attacking system sets the maximum value in Count (2**32), then the system under attack would stall for a significant period of time while it attempts to generate keys. TWAMP-compliant systems SHOULD have a configuration control to limit the maximum count value. The default @@ -1176,79 +1202,80 @@ /* * Configuration data nodes */ container twamp { description "TWAMP logical entity configuration grouping of four models which correspond to the four TWAMP logical entities Control-Client, Server, Session-Sender, and Session-Reflector - as illustrated in Fig. 1 of draft-ietf-ippm-twamp-yang."; + as illustrated in Fig. 1 of RFC XXXX."; container client { if-feature control-client; presence "Enables TWAMP Control-Client functionality."; description - "Configuration of the TWAMP Control-Client logical entity."; + "Configuration of the TWAMP Control-Client logical + entity."; leaf admin-state { type boolean; mandatory true; description "Indicates whether the device is allowed to operate as a TWAMP Control-Client."; } list mode-preference-chain { key priority; unique mode; leaf priority { type uint16; description "Indicates the Control-Client Mode preference priority - expressed as a 16-bit unsigned integer, where zero is the - highest priority and subsequent values monotonically - increasing."; + expressed as a 16-bit unsigned integer, where zero is + the highest priority and subsequent values + monotonically increasing."; } leaf mode { type twamp-modes; description "The supported TWAMP Mode matching the corresponding priority."; } description "Indicates the Control-Client preferred order of use of the supported TWAMP Modes. Depending on the Modes available in the TWAMP Server Greeting message (see Fig. 2 of RFC 7717), the - this Control-Client MUST choose the highest priority Mode - from the configured mode-preference-chain list."; + this Control-Client MUST choose the highest priority + Mode from the configured mode-preference-chain list."; } uses key-management; list ctrl-connection { key name; description "List of TWAMP Control-Client control connections. - Each item in the list describes a control connection that will be initiated by this Control-Client"; leaf name { type string; description - "A unique name used as a key to identify this individual - TWAMP-Control connection on the Control-Client device."; + "A unique name used as a key to identify this + individual TWAMP-Control connection on the + Control-Client device."; } leaf client-ip { type inet:ip-address; description "The IP address of the local Control-Client device, to be placed in the source IP address field of the IP header in TWAMP-Control (TCP) packets belonging to this control connection. If not configured, the device SHALL choose its own source IP address."; } @@ -1251,55 +1278,55 @@ IP header in TWAMP-Control (TCP) packets belonging to this control connection. If not configured, the device SHALL choose its own source IP address."; } leaf server-ip { type inet:ip-address; mandatory true; description "The IP address of the remote Server device, which the TWAMP-Control connection will be initiated to."; + } leaf server-tcp-port { type inet:port-number; default 862; description "This parameter defines the TCP port number that is to be used by this outgoing TWAMP-Control connection. Typically, this is the well-known TWAMP-Control - port number (862) as per RFC 5357 However, there are known - realizations of TWAMP in the field that were implemented - before this well-known port number was allocated. These - early implementations allowed the port number to be - configured. This parameter is therefore provided for - backward compatibility reasons."; + port number (862) as per RFC 5357 However, there are + known realizations of TWAMP in the field that were + implemented before this well-known port number was + allocated. These early implementations allowed the + port number to be configured. This parameter is + therefore provided for backward compatibility + reasons."; } leaf control-packet-dscp { type inet:dscp; default 0; description "The DSCP value to be placed in the IP header of TWAMP-Control (TCP) packets generated by this Control-Client."; - } leaf key-id { type string { length 1..80; } description "Indicates the KeyID value selected for this TWAMP-Control connection."; - } uses max-count; leaf client-tcp-port { type inet:port-number; config false; description "Indicates the source TCP port number used in the TWAMP-Control packets belonging to this control @@ -1303,22 +1330,22 @@ description "Indicates the source TCP port number used in the TWAMP-Control packets belonging to this control connection."; } leaf server-start-time { type uint64; config false; description - "Indicates the Start-Time advertized by the Server in the - Server-Start message (RFC 4656, Section 3.1), + "Indicates the Start-Time advertized by the Server in + the Server-Start message (RFC 4656, Section 3.1), representing the time when the current instantiation of the Server started operating. The timestamp format follows RFC 1305 according to Section 4.1.2 of RFC 4656."; } leaf repeat-count { type uint64; config false; description @@ -1334,46 +1361,46 @@ description "Indicates the current state of the TWAMP-Control connection state."; } leaf selected-mode { type twamp-modes; config false; description "The TWAMP Mode that the Control-Client has chosen for - this control connection as set in the Mode field of the - Set-Up-Response message"; + this control connection as set in the Mode field of + the Set-Up-Response message"; reference "RFC 4656, Section 3.1."; } leaf token { type binary { length 64; } config false; description "This parameter holds the 64 octets containing the concatenation of a 16-octet Challenge, a 16-octet AES Session-key used for encryption, and a 32-octet - HMAC-SHA1 Session-key used for authentication; see also - the last paragraph of Section 6 in RFC 4656. + HMAC-SHA1 Session-key used for authentication; see + also the last paragraph of Section 6 in RFC 4656. If the Mode defined in RFC 7717 is selected (selected-mode), Token is limited to 16 octets."; reference "RFC 4086: Randomness Requirements for Security - RFC 7717: IKEv2-Derived Shared Secret Key for the One-Way - Active Measurement Protocol (OWAMP) and Two-Way Active - Measurement Protocol (TWAMP)"; + RFC 7717: IKEv2-Derived Shared Secret Key for the + One-Way Active Measurement Protocol (OWAMP) and + Two-Way Active Measurement Protocol (TWAMP)"; } leaf client-iv { type binary { length 16; } config false; description "Indicates the Control-Client Initialization Vector (Client-IV), that is generated randomly by the @@ -1382,25 +1409,26 @@ Client-IV merely needs to be unique (i.e., it MUST never be repeated for different sessions using the same secret key; a simple way to achieve that without the use of cumbersome state is to generate the Client-IV values using a cryptographically secure pseudo-random number source. If the Mode defined in RFC 7717 is selected (selected-mode), Client-IV is limited to 12 octets."; reference - "RFC 4656: A One-way Active Measurement Protocol (OWAMP) + "RFC 4656: A One-way Active Measurement Protocol + (OWAMP). - RFC 7717: IKEv2-Derived Shared Secret Key for the One-Way - Active Measurement Protocol (OWAMP) and Two-Way Active - Measurement Protocol (TWAMP)"; + RFC 7717: IKEv2-Derived Shared Secret Key for the + One-Way Active Measurement Protocol (OWAMP) and + Two-Way Active Measurement Protocol (TWAMP)"; } list test-session-request { key name; description "Information associated with the Control-Client for this test session"; leaf name { type string; @@ -1437,53 +1465,55 @@ } default autoallocate; description "The UDP port number that is to be used by the Session-Sender for this TWAMP-Test session. The number is restricted to the dynamic port range. By default the Control-Client SHALL auto-allocate a UDP port number for this TWAMP-Test session. - The configured (or auto-allocated) value is advertized - in the Sender Port field of the Request-TW-session - message (see Section 3.5 of RFC 5357). Note that - in the scenario where a device auto-allocates a UDP - port number for a session, and the repeat parameter - for that session indicates that it should be - repeated, the device is free to auto-allocate a - different UDP port number when it negotiates the - next (repeated) iteration of this session."; + The configured (or auto-allocated) value is + advertized in the Sender Port field of the + Request-TW-session message (see Section 3.5 of + RFC 5357). Note that in the scenario where a device + auto-allocates a UDP port number for a session, and + the repeat parameter for that session indicates that + it should be repeated, the device is free to + auto-allocate a different UDP port number when it + negotiates the next (repeated) iteration of this + session."; } leaf reflector-ip { type inet:ip-address; mandatory true; description "The IP address belonging to the remote Session-Reflector device to which the TWAMP-Test session will be initiated. This value will be used to populate the receiver address field of the Request-TW-Session message."; } leaf reflector-udp-port { type uint32 { range "862 | 49152..65535"; } description "This parameter defines the UDP port number that will be used by the Session-Reflector for - this TWAMP-Test session. The default number is within - to the dynamic port range and is to be placed in - the Receiver Port field of the Request-TW-Session - message. The new well-known port (862) MAY be used."; + this TWAMP-Test session. The default number is + within to the dynamic port range and is to be placed + in the Receiver Port field of the Request-TW-Session + message. The new well-known port (862) MAY be + used."; } leaf timeout { type uint64; units seconds; default 2; description "The length of time (in seconds) that the Session-Reflector should continue to respond to packets belonging to this TWAMP-Test session after @@ -1534,24 +1563,23 @@ (but not before the TWAMP Start-Sessions command is issued; see Section 3.4 of RFC 5357). The start-time value is placed in the Start Time field of the Request-TW-Session message. The timestamp format follows RFC 1305 as per Section 3.5 of RFC 4656. The default value of 0 indicates that the session - will be started as soon as the Start-Sessions message - is received."; + will be started as soon as the Start-Sessions + message is received."; } - leaf repeat { type union { type uint32 { range 0..4294967294; } type enumeration { enum forever { description "Indicates that the test session SHALL be repeated *forever* using the information in @@ -1599,21 +1627,22 @@ } list pm-reg-list { key pm-index; leaf pm-index { type uint16; description "Numerical index value of a Registered Metric in the Performance Metric Registry (see ietf-ippm-metric-registry). Output statistics - are specified in the corresponding Registry entry."; + are specified in the corresponding Registry + entry."; } description "A list of one or more Performance Metric Registry Index values, which communicate packet stream characteristics along with one or more metrics to be measured. All members of the pm-reg-list MUST have the same stream characteristics, such that they combine to specify all metrics that shall be measured on @@ -1874,83 +1904,86 @@ list test-session{ key name; description "List of TWAMP Session-Sender test sessions."; leaf name { type string; description "A unique name for this TWAMP-Test session to be used - for identifying this test session by the Session-Sender - logical entity."; + for identifying this test session by the + Session-Sender logical entity."; } leaf ctrl-connection-name { type string; config false; description "The name of the parent TWAMP-Control connection that - is responsible for negotiating this TWAMP-Test session."; + is responsible for negotiating this TWAMP-Test + session."; } leaf fill-mode { type padding-fill-mode; default zero; description "Indicates whether the padding added to the TWAMP-Test (UDP) packets will contain pseudo-random numbers, or whether it should consist of all zeroes, as per Section 4.2.1 of RFC 5357."; } leaf number-of-packets { type uint32; mandatory true; description "The overall number of TWAMP-Test (UDP) packets to be - transmitted by the Session-Sender for this test session."; + transmitted by the Session-Sender for this test + session."; } choice packet-distribution { description "Indicates the distribution to be used for transmitting the TWAMP-Test (UDP) packets."; case periodic { leaf periodic-interval { type decimal64 { fraction-digits 5; } units seconds; mandatory true; description - "Indicates the time to wait (in seconds) between the - first bits of TWAMP-Test (UDP) packet transmissions for - this test session."; + "Indicates the time to wait (in seconds) between + the first bits of TWAMP-Test (UDP) packet + transmissions for this test session."; reference "RFC 3432: Network performance measurement with periodic streams"; } } case poisson { leaf lambda { type decimal64 { fraction-digits 5; } units seconds; mandatory true; description "Indicates the average time interval (in seconds) between packets in the Poisson distribution. - The packet is calculated using the reciprocal of lambda - and the TWAMP-Test packet size (which depends on the - selected Mode and the packet padding)."; + The packet is calculated using the reciprocal of + lambda and the TWAMP-Test packet size (which + depends on the selected Mode and the packet + padding)."; reference "RFC 2330: Framework for IP Performance Metrics"; } leaf max-interval { type decimal64 { fraction-digits 5; } units seconds; description "Indicates the maximum time (in seconds) @@ -1965,47 +1998,48 @@ leaf state { type sender-session-state; config false; description "Indicates the Session-Sender test session state."; } uses maintenance-statistics; } } - container session-reflector { if-feature session-reflector; presence "Enables TWAMP Session-Reflector functionality."; description - "Configuration of the TWAMP Session-Reflector logical entity"; + "Configuration of the TWAMP Session-Reflector logical + entity"; leaf admin-state { type boolean; mandatory true; description "Indicates whether the device is allowed to operate as a TWAMP Session-Reflector."; } leaf refwait { type uint32 { range 1..604800; } units seconds; default 900; description - "The Session-Reflector MAY discontinue any session that has - been started when no packet associated with that session has - been received for REFWAIT seconds. As per Section 3.1 of - RFC 5357, this timeout allows a Session-Reflector to free up - resources in case of failure."; + "The Session-Reflector MAY discontinue any session that + has been started when no packet associated with that + session has been received for REFWAIT seconds. As per + Section 3.1 of RFC 5357, this timeout allows a + Session-Reflector to free up resources in case of + failure."; } list test-session { key "sender-ip sender-udp-port reflector-ip reflector-udp-port"; config false; description "TWAMP Session-Reflectortest sessions."; @@ -2061,39 +2093,40 @@ "The IP address on the Control-Client device, which is the source IP address used in the TWAMP-Control (TCP) packets belonging to the parent control connection that negotiated this test session."; } leaf parent-connection-client-tcp-port { type inet:port-number; description "The source TCP port number used in the TWAMP-Control - (TCP) packets belonging to the parent control connection - that negotiated this test session."; + (TCP) packets belonging to the parent control + connection that negotiated this test session."; } leaf parent-connection-server-ip { type inet:ip-address; description "The IP address of the Server device, which is the destination IP address used in the TWAMP-Control (TCP) packets belonging to the parent control connection that negotiated this test session."; } leaf parent-connection-server-tcp-port { type inet:port-number; description - "The destination TCP port number used in the TWAMP-Control - (TCP) packets belonging to the parent control connection - that negotiated this test session."; + "The destination TCP port number used in the + TWAMP-Control (TCP) packets belonging to the parent + control connection that negotiated this test + session."; } leaf test-packet-dscp { type inet:dscp; description "The DSCP value present in the IP header of TWAMP-Test (UDP) packets belonging to this session."; } uses maintenance-statistics; @@ -2115,38 +2149,42 @@ A more elaborated example, which also includes authentication parameters, is provided in Appendix A. 6.1. Control-Client Figure 8 shows a configuration example for a Control-Client with client/admin-state enabled. In a real implementation following Figure 2 this would permit the initiation of TWAMP-Control connections and TWAMP-Test sessions. + [note: '\' line wrapping is for formatting only] + true Figure 8: XML instance enabling Control-Client operation. The following example shows a Control-Client with two instances of client/ctrl-connection, one called "RouterA" and another called "RouterB". Each TWAMP-Control connection is to a different Server. The control connection named "RouterA" has two test session requests. The TWAMP-Control connection named "RouterB" has no TWAMP-Test session requests. + [note: '\' line wrapping is for formatting only] + true RouterA 203.0.113.1 203.0.113.2 @@ -2168,20 +2206,22 @@ RouterB 203.0.113.1 203.0.113.3 + [note: '\' line wrapping is for formatting only] + true RouterA 2001:DB8:203:0:113::1 2001:DB8:203:0:113::2 @@ -2209,254 +2249,245 @@ 6.2. Server Figure 9 shows a configuration example for a Server with server/ admin-state enabled, which permits a device following Figure 2 to respond to TWAMP-Control connections and TWAMP-Test sessions. + [note: '\' line wrapping is for formatting only] + true Figure 9: XML instance enabling Server operation. The following example presents a Server with the TWAMP-Control connection corresponding to the control connection name (client/ctrl- connection/name) "RouterA" presented in Section 6.1. + [note: '\' line wrapping is for formatting only] + true 203.0.113.1 16341 203.0.113.2 862 - - active - + active + [note: '\' line wrapping is for formatting only] + true 2001:DB8:203:0:113::1 16341 2001:DB8:203:0:113::2 862 - - active - + active 6.3. Session-Sender Figure 10 shows a configuration example for a Session-Sender with session-sender/admin-state enabled, which permits a device following Figure 2 to initiate TWAMP-Test sessions. + [note: '\' line wrapping is for formatting only] + true Figure 10: XML instance enabling Session-Sender operation. The following configuration example shows a Session-Sender with the two TWAMP-Test sessions presented in Section 6.1. + [note: '\' line wrapping is for formatting only] + true Test1 RouterA 900 1 - setup Test2 - - RouterA - + RouterA 900 1 2 - setup 6.4. Session-Reflector This configuration example shows a Session-Reflector with session- reflector/admin-state enabled, which permits a device following Figure 2 to respond to TWAMP-Test sessions. + [note: '\' line wrapping is for formatting only] + true Figure 11: XML instance enabling Session-Reflector operation. The following example shows the two Session-Reflector TWAMP-Test sessions corresponding to the test sessions presented in Section 6.3. + [note: '\' line wrapping is for formatting only] + true 203.0.113.3 54000 203.0.113.4 50001 1232 - - 203.0.113.1 - - - 16341 - - - 203.0.113.2 - - - 862 - + 203.0.113.1 + 16341 + 203.0.113.2 + 862 2 2 1 1 203.0.113.1 54001 192.68.0.2 50001 178943 - - 203.0.113.1 - - - 16341 - - - 203.0.113.2 - - - 862 - + 203.0.113.1 + 16341 + 203.0.113.2 + 862 21 21 20 20 + [note: '\' line wrapping is for formatting only] + true 203.0.113.3 54000 203.0.113.4 54001 1232 - - 203.0.113.1 - - - 16341 - - - 203.0.113.2 - - - 862 - + 203.0.113.1 + 16341 + 203.0.113.2 + 862 2 2 1 1 - 203.0.113.1 54001 192.68.0.2 55001 178943 - - 203.0.113.1 - - - 16341 - - - 203.0.113.2 - - - 862 - + 203.0.113.1 + 16341 + 203.0.113.2 + 862 21 21 20 20 7. Security Considerations The YANG module defined in Section 5 is designed to be accessed, among other protocols, via NETCONF [RFC6241]. Protocols like NETCONF use a secure transport layer like SSH that is mandatory to implement. - The NETCONF Access Control Module (NACM) [RFC6536] provides the means + The NETCONF Access Control Module (NACM) [RFC8341] provides the means to restrict access for particular users to a pre-configured set of NETCONF protocol operations and attributes. There are a number of nodes defined in this YANG module which are writeable. These data nodes may be considered sensitive and vulnerable to attacks in some network environments. Ability to write into these nodes without proper protection can have a negative effect on the devices that support this feature. Examples of nodes that are particularly vulnerable include several @@ -2500,23 +2531,21 @@ Kostas Pentikousis was partially supported by FP7 UNIFY (http://fp7-unify.eu), a research project partially funded by the European Community under the Seventh Framework Program (grant agreement no. 619609). The views expressed here are those of the authors only. The European Commission is not liable for any use that may be made of the information in this document. 10. Contributors - Lianshu Zheng, Huawei Technologies, China - - Email: vero.zheng@huawei.com + Lianshu Zheng. 11. References 11.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . @@ -2542,424 +2571,414 @@ [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", RFC 6020, DOI 10.17487/RFC6020, October 2010, . [RFC6038] Morton, A. and L. Ciavattone, "Two-Way Active Measurement Protocol (TWAMP) Reflect Octets and Symmetrical Size Features", RFC 6038, DOI 10.17487/RFC6038, October 2010, . + [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", + RFC 6991, DOI 10.17487/RFC6991, July 2013, + . + [RFC7717] Pentikousis, K., Ed., Zhang, E., and Y. Cui, "IKEv2-Derived Shared Secret Key for the One-Way Active Measurement Protocol (OWAMP) and Two-Way Active Measurement Protocol (TWAMP)", RFC 7717, DOI 10.17487/RFC7717, December 2015, . + [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", + RFC 7950, DOI 10.17487/RFC7950, August 2016, + . + + [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC + 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, + May 2017, . + 11.2. Informative References [I-D.ietf-ippm-metric-registry] Bagnulo, M., Claise, B., Eardley, P., Morton, A., and A. Akhter, "Registry for Performance Metrics", draft-ietf- - ippm-metric-registry-13 (work in progress), October 2017. + ippm-metric-registry-14 (work in progress), March 2018. [I-D.unify-nfvrg-challenges] Szabo, R., Csaszar, A., Pentikousis, K., Kind, M., Daino, D., Qiang, Z., and H. Woesner, "Unifying Carrier and Cloud Networks: Problem Statement and Challenges", draft-unify- nfvrg-challenges-04 (work in progress), July 2016. [I-D.unify-nfvrg-devops] Meirosu, C., Manzalini, A., Steinert, R., Marchetto, G., Pentikousis, K., Wright, S., Lynch, P., and W. John, "DevOps for Software-Defined Telecom Infrastructures", draft-unify-nfvrg-devops-06 (work in progress), July 2016. [NSC] John, W., Pentikousis, K., et al., "Research directions in network service chaining", Proc. SDN for Future Networks and Services (SDN4FNS), Trento, Italy IEEE, November 2013. - [RFC2898] Kaliski, B., "PKCS #5: Password-Based Cryptography - Specification Version 2.0", RFC 2898, - DOI 10.17487/RFC2898, September 2000, - . - [RFC4086] Eastlake 3rd, D., Schiller, J., and S. Crocker, "Randomness Requirements for Security", BCP 106, RFC 4086, DOI 10.17487/RFC4086, June 2005, . [RFC5618] Morton, A. and K. Hedayat, "Mixed Security Mode for the Two-Way Active Measurement Protocol (TWAMP)", RFC 5618, DOI 10.17487/RFC5618, August 2009, . [RFC5938] Morton, A. and M. Chiba, "Individual Session Control Feature for the Two-Way Active Measurement Protocol (TWAMP)", RFC 5938, DOI 10.17487/RFC5938, August 2010, . [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., and A. Bierman, Ed., "Network Configuration Protocol (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, . - [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration - Protocol (NETCONF) Access Control Model", RFC 6536, - DOI 10.17487/RFC6536, March 2012, - . - [RFC7426] Haleplidis, E., Ed., Pentikousis, K., Ed., Denazis, S., Hadi Salim, J., Meyer, D., and O. Koufopavlou, "Software- Defined Networking (SDN): Layers and Architecture Terminology", RFC 7426, DOI 10.17487/RFC7426, January 2015, . + [RFC8018] Moriarty, K., Ed., Kaliski, B., and A. Rusch, "PKCS #5: + Password-Based Cryptography Specification Version 2.1", + RFC 8018, DOI 10.17487/RFC8018, January 2017, + . + [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, . + [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration + Access Control Model", STD 91, RFC 8341, + DOI 10.17487/RFC8341, March 2018, + . + Appendix A. Detailed Data Model Examples This appendix extends the example presented in Section 6 by configuring more fields such as authentication parameters, DSCP values and so on. A.1. Control-Client + [note: '\' line wrapping is for formatting only] + true 0 authenticated 1 unauthenticated KeyClient1ToRouterA - secret1 + c2VjcmV0MQ== KeyForRouterB - secret2 + c2VjcmV0Mg0K RouterA 203.0.113.1 203.0.113.2 - 32 + 32 KeyClient1ToRouterA Test1 203.0.113.3 54000 203.0.113.4 55000 64 0 - ok - 1232 Test2 203.0.113.1 54001 203.0.113.2 55001 128 0 - ok - 178943 + [note: '\' line wrapping is for formatting only] + true 0 authenticated 1 unauthenticated KeyClient1ToRouterA - secret1 + c2VjcmV0MQ== KeyForRouterB - secret2 + c2VjcmV0Mg0K + RouterA 2001:DB8:203:0:113::1 2001:DB8:203:0:113::2 - 32 + 32 KeyClient1ToRouterA Test1 2001:DB8:10:1:1::1 54000 2001:DB8:10:1:1::2 55000 64 0 - ok - 1232 Test2 2001:DB8:203:0:113::1 54001 2001:DB8:203:0:113::2 55001 128 0 - ok - 178943 A.2. Server + [note: '\' line wrapping is for formatting only] + true 1800 - 32 + 32 authenticated unauthenticated - 1024 + 30 KeyClient1ToRouterA - secret1 + c2VjcmV0MQ== KeyClient10ToRouterA - secret10 + c2VjcmV0MTANCg== 203.0.113.1 16341 203.0.113.2 862 - - active - - 32 + 32 unauthenticated KeyClient1ToRouterA - 1024 + 30 + [note: '\' line wrapping is for formatting only] + true 1800 - 32 + 32 authenticated unauthenticated - 1024 + 30 KeyClient1ToRouterA - secret1 + c2VjcmV0MQ== KeyClient10ToRouterA - secret10 + c2VjcmV0MTANCg== 2001:DB8:203:0:113::1 16341 2001:DB8:203:0:113::2 862 - - active - - - 32 + 32 unauthenticated KeyClient1ToRouterA - 1024 + 30 + A.3. Session-Sender + [note: '\' line wrapping is for formatting only] + true Test1 RouterA zero 900 1 - setup 2 2 1 1 Test2 - - RouterA - + RouterA random 900 1 2 - setup 21 21 20 20 A.4. Session-Reflector + [note: '\' line wrapping is for formatting only] + - - true - + true 203.0.113.3 54000 203.0.113.4 55000 1232 - - 203.0.113.1 - - - 16341 - - - 203.0.113.2 - - - 862 - - 32 + 203.0.113.1 + 16341 + 203.0.113.2 + 862 + 32 2 2 1 1 203.0.113.1 54001 192.68.0.2 55001 178943 - - 203.0.113.1 - - - 16341 - - - 203.0.113.2 - - - 862 - - 32 + 203.0.113.1 + 16341 + 203.0.113.2 + 862 + 32 21 21 20 20 + [note: '\' line wrapping is for formatting only] true 2001:DB8:10:1:1::1 54000 2001:DB8:10:1:1::2 55000 1232 - - 2001:DB8:203:0:113::1 - - - 16341 - - - 2001:DB8:203:0:113::2 - - - 862 - - 32 + 2001:DB8:203:0:113::1 + 16341 + 2001:DB8:203:0:113::2 + 862 + 32 2 2 1 1 2001:DB8:203:0:113::1 54001 2001:DB8:192:68::2 55001 178943 - - 2001:DB8:203:0:113::1 - - - 16341 - - - 2001:DB8:203:0:113::2 - - - 862 - - 32 + 2001:DB8:203:0:113::1 + 16341 + 2001:DB8:203:0:113::2 + 862 + 32 21 21 20 20 Appendix B. TWAMP Operational Commands