Two-Way Active Measurement Protocol (TWAMP) Data Model

The Two-Way Active Measurement Protocol (TWAMP) can be used to measure network performance parameters such as latency, bandwidth, and packet loss by sending probe packets and monitoring their experience in the network. To date, TWAMP implementations do not come with a standard management framework and, as such, configuration depends on the various proprietary mechanisms developed by the corresponding TWAMP vendor.

For large, virtualized, and dynamically instantiated infrastructures where network functions are placed according to orchestration algorithms as discussed in , proprietary mechanisms for managing TWAMP measurements have severe limitations. For current deployments, the lack of standardized programmable data model limits the flexibility to dynamically instantiate TWAMP-based measurement across equipment from different vendors. We note that earlier efforts to define, for example, a TWAMP Management Information Base (MIB) did not advance. As we move forward, two major trends call for revisiting the standardization on 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 and programmable control and management planes 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 .

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 .

The rest of this document is organized as follows. presents the scope and applicability of this document. provides a high-level overview of the TWAMP data model. details the configuration parameters of the data model and specifies the YANG module. lists illustrative examples which conform to the YANG module specified in this document. elaborates these examples further.

The purpose of this document is the specification of vendor-independent data model for TWAMP implementations. illustrates a redrawn version of the TWAMP logical model found in , Section 1.2. The figure is annotated with pointers to the UML diagrams provided in this document and associated with the data model of the four logical entities in a TWAMP deployment, namely the TWAMP Control-Client, Server, Session-Sender and Session-Reflector. As per , unlabeled links in the figure are unspecified and may be proprietary protocols.

| Server | +----------------+ +--------+ ^ ^ | | V V +----------------+ +-------------------+ | Session-Sender | <-- TWAMP-Test --> | Session-Reflector | +----------------+ +-------------------+ [Fig. 5] [Fig. 6] ]]> As discussed in , a TWAMP implementation may follow a simplified logical model, in which the same node acts both as the Control-Client and Session-Sender, while another node acts at the same time as the TWAMP Server and Session-Reflector. illustrates this simplified logical model and indicates the interaction between the TWAMP configuration client and server using, for instance, NETCONF or RESTCONF . Note, however, that the specific protocol used to communicate the TWAMP configuration parameters specified herein is outside the scope of this document.

A TWAMP data model includes four categories of configuration items. Global configuration items relate to parameters that are set on a per device level. For example, the administrative status of the device with respect to whether it allows TWAMP sessions and if so in what capacity (e.g. Control-Client, Server or both) are typical instances of global configuration items. A second category includes attributes that can be configured on a per control connection basis, such as the Server IP address. A third category includes attributes related to per-test session attributes, for instance setting different values in the Differentiated Services Code Point (DSCP) field. Finally, the data model could include attributes that relate to the operational state of the TWAMP implementation. As we describe the TWAMP data model in the remaining sections of this document, readers should keep in mind the functional entity grouping illustrated in .

A TWAMP Control-Client has an administrative status field set at the device level that indicates whether the node is enabled to function as such. Each TWAMP Control-Client is associated with zero or more TWAMP control connections. The main configuration parameters of each control connection are: A name which can be used to uniquely identify, at the Control-Client, a particular control connection. This name is necessary for programmability reasons because at the time of creation of a TWAMP control connection not all IP and TCP port information needed to uniquely identify the connection is available. The IP address of the interface the Control-Client will use for connections The IP address of the remote Server Authentication and Encryption attributes such as KeyID, Token and the Client Initialization Vector (Client-IV) . Each TWAMP control connection, in turn, is associated with zero or more test sessions. For each test session we note the following configuration items: The test session name that uniquely identifies a particular test session at the Control-Client and Session-Sender. Similarly to the control connections above, this unique test session name is needed because at the time of creation of a test session the source UDP port is not known to uniquely identify the test session. The IP address and UDP port number of the Session-Sender of the path under test by TWAMP The IP address and UDP port number of the Session-Reflector of said path Information pertaining to the test packet stream, such as the test starting time or whether the test should be repeated.

Each TWAMP Server has an administrative status field set at the device level to indicate whether the node is enabled to function as a TWAMP Server. Each TWAMP Server is associated with zero or more control connections. Each control connection is uniquely identified by the 4-tuple {Control-Client IP address, Control-Client TCP port number, Server IP address, Server TCP port}. Control connection configuration items on a TWAMP Server are read-only.

There is one TWAMP Session-Sender instance for each test session that is initiated from the sending device. Primary configuration fields include: The test session name that MUST be identical with the corresponding test session name on the TWAMP Control-Client () The control connection name, which along with the test session name uniquely identify the TWAMP Session-Sender instance Information pertaining to the test packet stream, such as, for example, the value used in the DSCP packet header field and the number of test packets.

Each TWAMP Session-Reflector is associated with zero or more test sessions. For each test session, the REFWAIT parameter can be configured. Read-only access to other data model parameters, such as the Sender IP address is foreseen. Each test session can be uniquely identified by the 4-tuple mentioned in .

This section defines the TWAMP data model using UML and describes all associated parameters.

The twampClient container (see ) holds items that are related to the configuration of the TWAMP Control-Client logical entity. These are divided up into items that are associated with the configuration of the Control-Client as a whole (e.g. clientAdminState) and items that are associated with individual control connections initiated by that Control-Client entity (twampClientCtrlConnection).

-------------------------| modePreferenceChain | | | +---------------------+ | | 1..* +-----------+ | priority | | |<>------| keyChain | | mode | +------------------+ +-----------+ +---------------------+ ^ | keyID | V | secretKey | | +-----------+ | 0..* +---------------------------+ | twampClientCtrlConnection | +---------------------------+ | ctrlConnectionName | 0..* +-----------------------+ | clientIp |<>-------| twampSessionRequest | | serverIp | +-----------------------+ | serverTcpPort | | testSessionName | | dscp | | senderIp | | keyId | | senderUdpPort | | dkLen | | reflectorIp | | clientTcpPort {ro} | | reflectorUdpPort | | serverStartTime {ro} | | timeout | | ctrlConnectionState {ro} | | paddingLength | | selectedMode {ro} | | startTime | | token {ro} | | repeat | | clientIv {ro} | | repeatInterval | +---------------------------+ | pmIndex | | testSessionState {ro} | | sid {ro} | +-----------------------+ ]]> The twampClient container includes an administrative parameter (clientAdminState) that controls whether the device is allowed to initiate TWAMP control and test sessions. The twampClient container holds a list which specifies the preferred Mode values according to their preferred order of use, including the authentication and encryption Modes. Specifically, modePreferenceChain lists each priority (expressed as a 16-bit unsigned integer, where zero is the highest priority and subsequent values monotonically increasing) with their corresponding mode (expressed as a 32-bit Hexadecimal value). Depending on the Modes available in the Server Greeting, the Control-Client MUST choose the highest priority Mode from the configured modePreferenceChain list. Note that the list of preferred Modes may set bit position combinations when necessary, such as when referring to the extended TWAMP features in , , and . If the Control-Client cannot determine an acceptable Mode, it MUST respond with zero Mode bits set in the Set-up Response message, indicating it will not continue with the control connection. In addition, the twampClient container holds a list named keyChain which relates KeyIDs with the respective secret keys. Both the Server and the Control-Client use the same mappings from KeyIDs to shared secrets. 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. keyId is a UTF-8 string, up to 80 octets in length (if the string is shorter, it is padded with zero octets), that tells the Server which shared secret the Control-Client wishes to use to authenticate or encrypt. The secretKey is the shared secret, an octet string of arbitrary length whose interpretation as a text string is unspecified. In the interest of interoperability, however, the UTF-8 text encoding MUST be used for secretKey. Each twampClient container also holds a list of twampClientCtrlConnection, where each item in the list describes a TWAMP control connection that will be initiated by this Control-Client. There SHALL be one instance of twampClientCtrlConnection per TWAMP Control (TCP) connection that is to be initiated from this device. The configuration items for twampClientCtrlConnection are: A unique name used as a key to identify this individual TWAMP control connection on the Control-Client device. The IP address of the local Control-Client device, to be placed in the source IP address field of the IP header in TWAMP TCP control packets belonging to this control connection. If not configured, the device SHALL choose its own source IP address. The IP address belonging to the remote Server device to which the control connection will be initiated to. 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 port number (862) . 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. The DSCP value to be placed in the TCP header of TWAMP-Control packets generated by this Control-Client. The keyId value that is selected for this control connection. KeyID a UTF-8 string, up to 80 octets in length (if the string is shorter, it is padded with zero octets). Intended length in octets of the derived key, a positive integer, at most (2^32 - 1) * hLen. The following twampClientCtrlConnection parameters are read-only: The source TCP port used in the TWAMP control packets belonging to this control connection. The Start-Time advertized by the Server in the Server-Start message (, Section 3.1). This is a timestamp representing the time when the current instantiation of the Server started operating. The control connection state can be either active or idle. The mode that the Control-Client has chosen for this control connection as set in the Mode field of the Set-Up-Response message (, Section 3.1). 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. AES Session-key and HMAC Session-key are generated randomly by the Control-Client. AES Session-key and HMAC Session-key MUST be generated with sufficient entropy not to reduce the security of the underlying cipher . The token itself is encrypted using the AES (Advanced Encryption Standard) in Cipher Block Chaining (CBC). Encryption MUST be performed using an Initialization Vector (IV) of zero and a key derived from the shared secret associated with KeyID. Challenge is the same as transmitted by the Server () in the clear; see also the last paragraph of Section 6 in . The Control-Client Initialization Vector (Client-IV) is generated randomly by the Control-Client. 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. Each twampClientCtrlConnection holds a list of twampSessionRequest. twampSessionRequest holds information associated with the Control-Client for this test session. This includes information that is associated with the Request-TW-Session/Accept-Session message exchange (, Section 3.5). The Control-Client is also responsible for scheduling and results collection for test sessions, so twampSessionRequest will also hold information related these actions (e.g. pmIndex, repeatInterval). There SHALL be one instance of twampSessionRequest for each test session that is to be negotiated by this control connection via a Request-TW-Session/Accept-Session exchange. The configuration items for twampSessionRequest are: A unique name for this test session to be used as a key for this test session on the Control-Client. The IP address of the Session-Sender device, which is to be placed in the source IP address field of the IP header in TWAMP UDP test packets belonging to this test session. This value will be used to populate the sender address field of the Request-TW-Session message. The UDP port number that is to be used by the Session-Sender for this test session. A value of zero indicates that the Control-Client will auto-allocate a UDP port for this test session. This value is advertized in the sender port field of the Request-TW-session message. 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. This parameter defines the UDP port number that will be used by the Session-Reflector for this test session. This value will be placed in the receiver port field of the Request-TW-Session message. The length of time (in seconds) that the Session-Reflector should continue to respond to packets belonging to this session after a Stop-Sessions control message has been received (, Section 3.8). This value will be placed in the timeout field of the Request-TW-Session message. The number of bytes of padding that will be added to the UDP test packets generated by the Session-Sender. This value will be placed in the Padding Length field of the Request-TW-Session message . Time when the session is to be started (but not before the Start-Sessions command is issued). This value is placed in the Start Time field of the Request-TW-Session message. A value of 0 indicates that the session will be started as soon as the Start-Sessions message is received. These two values together are used to determine if the test session is to be run repeatedly. Once a test session has completed, the repeat parameter is checked. If the value indicates that this test session is to run again, then the parent control connection for this test session is restarted - and negotiates a new instance of this test session. This may happen immediately after the test session completes (if the repeatInterval is set to 0). Otherwise, the Control-Client will wait for the number of minutes specified in the repeatInterval before negotiating the new instance of this test session. Numerical index value of a Registered Metric in the Performance Metric Registry . Output Statistics will be specified in the Registry entry. The following twampSessionRequest parameters are read-only: The test session state can be either accepted or indicate the respective error code. The SID allocated by the Server for this test session, and communicated back to the Control-Client in the SID field of the Accept-Session message; see Section 4.3 of .

The twampServer container (see ) holds items that are related to the configuration of the TWAMP Server logical entity (recall ).

------| keyChain | | servwait | +-----------+ | dscp | | keyID | | count | | secretKey | | maxCount | +-----------+ | modes | | salt {ro} | 0..* +--------------------------------+ | serverIv {ro} |<>------| twampServerCtrlConnection | | challenge {ro} | +--------------------------------+ +------------------+ | clientIp {ro} | | clientTcpPort {ro} | | serverIp {ro} | | serverTcpPort {ro} | | serverCtrlConnectionState {ro} | | dscp {ro} | | selectedMode {ro} | | keyID {ro} | | dkLen {ro} | | count {ro} | | maxCount {ro} | +--------------------------------+ ]]> A device operating in the Server role cannot configure attributes on a per control connection basis, as it has no foreknowledge of what incoming TWAMP control connections it will receive. As such, any parameter that the Server might want to apply to an incoming control connection must be configured at the overall Server level, and will then be applied to all incoming TWAMP control connections. Each twampServer container holds a list named keyChain which relates KeyIDs with the respective secret keys. As mentioned in , both the Server and the Control-Client use the same mappings from KeyIDs to shared secrets. 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. keyId is a UTF-8 string, up to 80 octets in length (if the string is shorter, it is padded with zero octets), that tells the Server which shared secret the Control-Client wishes to use to authenticate or encrypt. Each incoming control connection that is active on the Server will be represented by an instance of a twampServerCtrlConnection object. All items in the twampServerCtrlConnection object are read-only. The twampServer container items are as follows: This administrative parameter controls whether the device is allowed to operate as a TWAMP Server. As defined in the roles of Server and Session-Reflector can be played by the same host; recall . For a host operating in this manner, this parameter controls whether the device is allowed to respond to TWAMP control and test sessions. This parameter defines the well known TCP port number that is used by TWAMP. The Server will listen on this port for incoming TWAMP control connections. Although this is defined as a fixed value (862) in , there are several 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. TWAMP Control (TCP) session timeout, in seconds. The DSCP value to be placed in the TCP header of TWAMP-Control packets generated by the Server. Parameter used in deriving a key from a shared secret as described in Section 3.1 of , and are communicated to the Control-client as part of Server Greeting message. Count MUST be a power of 2. Count MUST be at least 1024. Count SHOULD be increased as more computing power becomes common. 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. Therefore, TWAMP-compliant systems SHOULD have a configuration control to limit the maximum Count value. The default maximum Count value SHOULD be 32768. The bit mask of TWAMP Modes this Server instance is willing to support; see IANA TWAMP Modes Registry. Each bit position set represents a mode; see TWAMP-Modes at http://www.iana.org/assignments/twamp-parameters/twamp-parameters.xhtml. Note: Modes requiring Authentication or Encryption MUST include the related attributes. The following parameters are read-only: A parameter used in deriving a key from a shared secret as described in Section 3.1 of . Salt MUST be generated pseudo-randomly (independently of anything else in the RFC) and is communicated to the Control-Client as part of the Server greeting message. The Server Initialization Vector (IV) is generated randomly by the server. Challenge is a random sequence of octets generated by the server. As described in challenge is used by the Control-Client to prove possession of a shared secret. There SHALL be one instance of twampServerCtrlConnection per incoming TWAMP TCP Control connection that is received and active on the Server device. All items in the twampServerCtrlConnection are read-only. Each instance of twampServerCtrlConnection uses the following 4-tuple as its unique key: clientIp, clientTcpPort, serverIp, serverTcpPort. The twampServerCtrlConnection container items are all read-only: The IP address on the remote Control-Client device, which is the source IP address used in the TWAMP TCP control packets belonging to this control connection. The source TCP port used in the TWAMP TCP control packets belonging to this control connection. The IP address of the local Server device, which is the destination IP address used in the TWAMP TCP control packets belonging to this control connection. The destination TCP port used in the TWAMP TCP control packets belonging to this control connection. This will usually be the same value as is configured under twampServer. However, in the event that the user re-configured twampServer:serverTcpPort after this control connection was initiated, this value will indicate the serverTcpPort that is actually in use for this control connection. The Server control connection state can be active or SERVWAIT. The DSCP value used in the header of the TCP control packets sent by the Server for this control connection. This will usually be the same value as is configured for twampServer:dscp under the twampServer. However, in the event that the user re-configures twampServer:dscp after this control connection is already in progress, this read-only value will show the actual dscp value in use by this control connection. The mode that was chosen for this control connection as set in the Mode field of the Set-Up-Response message. The keyId value that is in use by this control connection. KeyID a UTF-8 string, up to 80 octets in length (if the string is shorter, it is padded with zero octets). The Control-Client selects the keyID for the control connection. The dkLen value that is in use by this control connection. This will usually be the same value as is configured under twampServer. However, in the event that the user re-configured twampServer:dkLen after this control connection is already in progress, this read-only value will show the actual dkLen that is in use for this control connection. The count value that is in use by this control connection. This will usually be the same value as is configured under twampServer. However, in the event that the user re-configured twampServer:count after this control connection is already in progress, this read-only value will show the actual count that is in use for this control connection. The maxCount value that is in use by this control connection. This will usually be the same value as is configured under twampServer. However, in the event that the user re-configured twampServer:maxCount after this control connection is already in progress, this read-only value will show the actual maxCount that is in use for this control connection.

The twampSessionSender container, illustrated in , holds items that are related to the configuration of the TWAMP Session-Sender logical entity. There are no global configuration items that apply to the Session-Sender entity as a whole. There is one instance of twampSenderTestSession for each test session for which packets are being sent.

------| twampSenderTestSession | +--------------------+ +-------------------------+ | testSessionName | | ctrlConnectionName {ro} | | dscp | | dot1dPriority | | fillMode | | numberOfPackets | | senderSessionState {ro} | | sentPackets {ro} | | rcvPackets {ro} | | lastSentSeq {ro} | | lastRcvSeq {ro} | +-------------------------+ ^ V | 1 +--------------------+ | packetDistribution | +--------------------+ | fixed / poisson | +--------------------+ | | +--------------------+ | | fixedInterval | | | fixedIntervalUnits | | +--------------------+ | +----------------------+ | lambda | | lambdaUnits | | maxInterval | | truncationPointUnits | +----------------------+ ]]> The twampSenderTestSession container items are: A unique name for this test session to be used as a key for this test session by the Session-Sender logical entity. The name of the parent control connection that is responsible for negotiating this test session. The DSCP value to be placed in the UDP header of TWAMP-Control packets generated by the Session-Sender. Priority Code Point (PCP) value to place in the Ethernet header of the TWAMP UDP test frames transmitted for this test session. Indicates whether the padding added to the UDP test packets will contain pseudo-random numbers, or whether it should consist of all zeroes, as per Section 4.2.1 of . The overall number of UDP test packets to be transmitted by the Session-Sender for this test session. Defines whether test packets are to be transmitted with a fixed interval between them, or whether a Poisson distribution is to be used. If packetDistribution is set to fixed, these two values are used together to determine the fixed time to wait between test packet transmissions for this test session. fixedInterval is an unsigned floating point number, 8 significant digits. fixedIntervalUnits is one of seconds, milliseconds, microseconds, nanoseconds. If packetDistribution is Poisson, the lambda parameter defines the average rate of packet transmission. lambda is an unsigned floating point number, 8 significant digits. lambdaUnits defines the units of lambda in reciprocal seconds. If packetDistribution is Poisson, then this parameter keeps a stream active by setting a maximum time between packet transmissions. One of seconds, milliseconds, microseconds, nanoseconds. The following twampSenderTestSession parameters are read-only: This read-only item can be either Active or Idle. The number of UDP test packets belonging to this session that have been transmitted by the Session-Sender. The number of UDP test packets belonging to this session that have been received from the Session-Reflector. The round trip loss for a test session can be calculated as sentPackets - rcvPackets. The value in the sequence number field of the last UDP test packet transmitted for this test session. Sequence numbers start from zero - so this should always be one less than the sentPackets value. The value in the sequence number field of the last UDP test packet received for this test session. In the case of packet loss in the Session-Sender -> Session-Reflector direction, this value minus the lastSentSeq will identify the number of packets that were lost in the Session-Sender -> Session-Reflector direction.

The twampSessionReflector container, illustrated in , holds items that are related to the configuration of the TWAMP Session-Reflector logical entity. A device operating in the Session-Reflector role cannot configure attributes on a per-session basis, as it has no foreknowledge of what incoming sessions it will receive. As such, any parameter that the Session-Reflector might want to apply to an incoming test session must be configured at the overall Session-Reflector level, and will then be applied to all incoming sessions. Each incoming test session that is active on the Session-Reflector will be represented by an instance of a twampReflectorTestSession object. All items in the twampReflectorTestSession object are read-only.

------| twampReflectorTestSession | +-----------------------+ +------------------------------------+ | sid {ro} | | senderIp {ro} | | senderUdpPort {ro} | | reflectorIp {ro} | | reflectorUdpPort {ro} | | parentConnectionClientIp {ro} | | parentConnectionClientTcpPort {ro} | | parentConnectionServerIp {ro} | | parentConnectionServerTcpPort {ro} | | dscp {ro} | | sentPackets {ro} | | rcvPackets {ro} | | lastSentSeq {ro} | | lastRcvSeq {ro} | +------------------------------------+ ]]> The twampSessionReflector configuration items are: The Session-Reflector MAY discontinue any session that has been started when no packet associated with that session has been received for REFWAIT seconds. The default value of REFWAIT SHALL be 900 seconds, and this waiting time MAY be configurable. This timeout allows a Session-Reflector to free up resources in case of failure. Instances of twampSessionReflector:twampReflectorTestSession are indexed by a session identifier (SID). This is a value that is auto-allocated by the Server as test session requests are received, and communicated back to the Control-Client in the SID field of the Accept-Session message; see Section 4.3 of . When attempting to retrieve operational data for active test sessions from a Session-Reflector device, the user will not know what sessions 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 twampClient:twampClientCtrlConnection:twampSessionRequest and obtain the SID (see ). The user may then use this SID value as an index to retrieve an individual twampSessionReflector:twampReflectorTestSession 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 twampReflectorTestSession instances from the Session-Reflector device. This could be problematic if a large number of test sessions are currently active on that device. Each Session-Reflector test session contains the following 4-tuple: {parentConnectionClientIp, parentConnectionClientTcpPort, parentConnectionServerIp, parentConnectionServerTcpPort}. This 4-tuple corresponds to the equivalent 4-tuple {clientIp, clientTcpPort, serverIp, serverTcpPort} in the twampServerCtrlConnection object. This four4-tuple allows the user to trace back from the test session to the parent control connection that negotiated this test session. All data under twampReflectorTestSession is read-only: An auto-allocated identifier for this test session, that is unique within the context of this Server/Session-Reflector device only. This value will be communicated to the Control-Client that requested the test session in the SID field of the Accept-Session message. The IP address on the remote device, which is the source IP address used in the TWAMP UDP test packets belonging to this test session. The source UDP port used in the TWAMP UDP test packets belonging to this test session. The IP address of the local Session-Reflector device, which is the destination IP address used in the TWAMP UDP test packets belonging to this test session. The destination UDP port used in the TWAMP UDP test packets belonging to this test session. The IP address on the Control-Client device, which is the source IP address used in the TWAMP TCP control packets belonging to the parent control connection that negotiated this test session. The source TCP port used in the TWAMP TCP control packets belonging to the parent control connection that negotiated this test session. The IP address of the Server device, which is the destination IP address used in the TWAMP TCP control packets belonging to the parent control connection that negotiated this test session. The destination TCP port used in the TWAMP TCP control packets belonging to the parent control connection that negotiated this test session. The DSCP value present in the UDP header of TWAMP test packets belonging to this test session. The number of UDP test response packets that have been sent by the Session-Reflector for this test session. The number of UDP test packets that have been received by the Session-Reflector for this test session. Since the Session-Reflector should respond to every test packet it receives, the sentPackets and rcvPackets values should always be identical. The value in the sequence number field of the last UDP test response packet transmitted for this test session. The value in the sequence number field of the last UDP test packet received for this test session.

This section presents the TWAMP YANG data tree defined in this document. Readers should keep in mind that the limit of 72 characters per line forces us to introduce artificial line breaks in some tree nodes.

This section presents the TWAMP YANG module defined in this document.

file "ietf-twamp@2015-03-06.yang" module twamp { namespace "urn:ietf:params:xml:ns:yang:ietf-twamp"; //namespace need to be assigned by IANA prefix "twamp"; import ietf-inet-types { prefix inet; } organization "IETF IPPM (IP Performance Metrics) Working Group"; contact "draft-cmzrjp-ippm-twamp-yang@tools.ietf.org"; description "TWAMP Data Model"; revision "2015-03-06" { description "Initial version. RFC5357 is covered. RFC5618, RFC5938 and RFC6038 are not covered."; } feature controlClient { description "This feature relates to the device functions as the TWAMP Control-Client."; } feature server { description "This feature relates to the device functions as the TWAMP Server."; } feature sessionSender { description "This feature relates to the device functions as the TWAMP Session-Sender."; } feature sessionReflector { description "This feature relates to the device functions as the TWAMP Session-Reflector."; } grouping maintenanceStatistics { leaf sentPackets { config "false"; type uint32; } leaf rcvPackets { config "false"; type uint32; } leaf lastSentSeq { config "false"; type uint32; } leaf lastRcvSeq { config "false"; type uint32; } } container twamp { container twampClient { if-feature controlClient; leaf clientAdminState { mandatory "true"; type boolean; description "Indicates whether this device is allowed to run TWAMP to initiate control/test sessions"; } list modePreferenceChain { key "priority"; unique "mode"; leaf priority { type uint16; } leaf mode { type enumeration { enum unauthenticated { value "1"; } enum authenticated { value "2"; } enum encrypted { value "4"; } enum unauthtestencrpytcontrol { value "8"; } enum individualsessioncontrol { value "16"; } enum reflectoctets { value "32"; } enum symmetricalsize { value "64"; } } } } list keyChain { key "keyId"; leaf keyId { type string { length "1..80"; } } leaf secretKey { type string; } } list twampClientCtrlConnection { key "ctrlConnectionName"; leaf ctrlConnectionName { type "string"; description "A unique name used as a key to identify this individual TWAMP control connection on the Control-Client device."; } leaf clientIp { type inet:ip-address; } leaf serverIp { config "true"; type inet:ip-address; } leaf serverTcpPort { type inet:port-number; } leaf dscp{ type inet:dscp; description "The DSCP value to be placed in the IP header of the TWAMP TCP Control packets generated by the Control-Client"; } leaf keyId { type string { length "1..80"; } } leaf dkLen { type uint32; } leaf clientTcpPort { config "false"; type inet:port-number; } leaf serverStartTime { config "false"; type uint64; } leaf ctrlConnectionState { config "false"; type enumeration { enum active { description "Control session is active."; } enum idle { description "Control session is idle."; } } } leaf selectedMode { config "false"; type enumeration { enum unauthenticated { value "1"; } enum authenticated { value "2"; } enum encrypted { value "4"; } enum unauthtestencrpytcontrol { value "8"; } enum individualsessioncontrol { value "16"; } enum reflectoctets { value "32"; } enum symmetricalsize { value "64"; } } } leaf token { config "false"; type string { length "1..64"; } description "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"; } leaf clientIv{ config "false"; type string { length "1..16"; } description "16 octets, Client-IV is generated randomly by the Control-Client."; } list twampSessionRequest { key "testSessionName"; leaf testSessionName { type "string"; } leaf senderIp { type inet:ip-address; } leaf senderUdpPort { type inet:port-number; } leaf reflectorIp { type inet:ip-address; } leaf reflectorUdpPort { type inet:port-number; } leaf timeout { type uint64; description "The time Session-Reflector MUST wait after receiving a Stop-Session message"; } leaf paddingLength { type uint32{ range "64..1500"; } description "The number of bytes of padding that should be added to the UDP test packets generated by the sender."; } leaf startTime { type uint64; } leaf repeat { type boolean; } leaf repeatInterval { type uint32; when "repeat='true'"; description "Repeat interval (in minutes)"; } leaf pmIndex { type uint16; description "Numerical index value of a Registered Metric in the Performance Metric Registry"; } leaf testSessionState { config "false"; type enumeration { enum ok { value 0; description "Test session is accepted."; } enum failed { value 1; description "Failure, reason unspecified (catch-all)."; } enum internalError { value 2; description "Internal error."; } enum notSupported { value 3; description "Some aspect of request is not supported."; } enum permanentResLimit { value 4; description "Cannot perform request due to permanent resource limitations."; } enum tempResLimit { value 5; description "Cannot perform request due to temporary resource limitations."; } } } leaf sid{ config "false"; type string; } } } } container twampServer{ if-feature server; leaf serverAdminState{ type boolean; mandatory "true"; description "Indicates whether this device is allowed to run TWAMP to respond to control/test sessions"; } leaf serverTcpPort { type inet:port-number; default "862"; } leaf servwait { type uint32 { range 1..604800; } default 900; description "SERVWAIT (TWAMP Control (TCP) session timeout), default value is 900"; } leaf dscp { type inet:dscp; description "The DSCP value to be placed in the IP header of the TWAMP TCP Control packets generated by the Server"; } leaf count { type uint32 { range 1024..4294967295; } } leaf maxCount { type uint32 { range 1024..4294967295; } default 32768; } leaf modes { type bits { bit unauthenticated { position 0; } bit authenticated { position 1; } bit encrypted { position 2; } bit unauthtestencryptcontrol { position 3; } bit individualsessioncontrol { position 4; } bit reflectoctets { position 5; } bit symmetricalsize { position 6; } } } leaf salt{ config "false"; type string { length "1..16"; } description "Salt MUST be generated pseudo-randomly"; } leaf serverIv { config "false"; type string { length "1..16"; } description "16 octets, Server-IV is generated randomly by the Control-Client."; } leaf challenge { config "false"; type string { length "1..16"; } description "Challenge is a random sequence of octets generated by the Server"; } list keyChain { key "keyId"; leaf keyId { type string { length "1..80"; } } leaf secretKey { type string; } } list twampServerCtrlConnection { key "clientIp clientTcpPort serverIp serverTcpPort"; config "false"; leaf clientIp { type inet:ip-address; } leaf clientTcpPort { type inet:port-number; } leaf serverIp { type inet:ip-address; } leaf serverTcpPort { type inet:port-number; } leaf serverCtrlConnectionState { type enumeration { enum "active"; enum "servwait"; } } leaf dscp { type inet:dscp; description "The DSCP value used in the header of the TCP control packets sent by the Server for this control connection. This will usually be the same value as is configured for twampServer:dscp under the twampServer. However, in the event that the user re-configures twampServer:dscp after this control connection is already in progress, this read-only value will show the actual dscp value in use by this control connection."; } leaf selectedMode { type enumeration { enum unauthenticated { value "1"; } enum authenticated { value "2"; } enum encrypted { value "4"; } enum unauthtestencrpytcontrol { value "8"; } enum individualsessioncontrol { value "16"; } enum reflectoctets { value "32"; } enum symmetricalsize { value "64"; } } description "The mode that was chosen for this control connection as set in the Mode field of the Set-Up-Response message."; } leaf keyId { type string { length "1..80"; } description "The keyId value that is in use by this control connection."; } leaf dkLen { type uint32; description "The dkLen value that is in use by this control connection. This will usually be the same value as is configured under twampServer. In the event that the user re-configured twampServer:dkLen after this control connection is already in progress, this read-only value will show the actual dkLen that is in use for this control connection."; } leaf count { type uint32 { range 1024..4294967295; } description "The count value that is in use by this control connection. This will usually be the same value as is configured under twampServer. However, in the event that the user re-configured twampServer:count after this control connection is already in progress, this read-only value will show the actual count that is in use for this control connection."; } leaf maxCount { type uint32 { range 1024..4294967295; } description "The maxCount value that is in use by this control connection. This will usually be the same value as is configured under twampServer. However, in the event that the user re-configured twampServer:maxCount after this control connection is already in progress, this read-only value will show the actual maxCount that is in use for this control connection."; } } } container twampSessionSender { if-feature sessionSender; list twampSenderTestSession { key "testSessionName"; leaf testSessionName { type string; description "A unique name for this test session to be used as a key for this test session by the Session-Sender logical entity."; } leaf ctrlConnectionName { config "false"; type "string"; description "The name of the parent control connection that is responsible for negotiating this test session."; } leaf dscp { type inet:dscp; description "The DSCP value to be placed in the header of TWAMP UDP test packets generated by the sender."; } leaf dot1dPriority { type uint8 { range "0..7"; } } leaf fillMode { type enumeration { enum zero; enum random; } default zero; } leaf numberOfPackets { type uint32; description "The overall number of UDP test packets to be transmitted by the sender for this test session."; } choice packetDistribution { case fixed { leaf fixedInterval { type uint32; } leaf fixedIntervalUnits { type enumeration { enum seconds; enum milliseconds; enum microseconds; enum nanoseconds; } } } case poisson { leaf lambda { type uint32; } leaf lambdaUnits { type uint32; } leaf maxInterval { type uint32; } leaf truncationPointUnits { type enumeration { enum seconds; enum milliseconds; enum microseconds; enum nanoseconds; } } } } leaf senderSessionState { config "false"; type enumeration { enum setup { description "Test session is active."; } enum failure { description "Test session is idle."; } } } uses maintenanceStatistics; } } container twampSessionReflector { if-feature sessionReflector; leaf refwait { config "true"; type uint32 { range 1..604800; } default 900; description "REFWAIT(TWAMP test session timeout), the default value is 900"; } list twampReflectorTestSession { key "senderIp senderUdpPort reflectorIp reflectorUdpPort"; config "false"; leaf sid { type string; } leaf senderIp { type inet:ip-address; } leaf senderUdpPort { type inet:port-number; } leaf reflectorIp { type inet:ip-address; } leaf reflectorUdpPort { type inet:port-number; } leaf parentConnectionClientIp { type inet:ip-address; } leaf parentConnectionClientTcpPort { type inet:port-number; } leaf parentConnectionServerIp { type inet:ip-address; } leaf parentConnectionServerTcpPort { type inet:port-number; } leaf dscp { type inet:dscp; description "The DSCP value placed in the header of TWAMP UDP test packets generated by the Session-Sender."; } uses maintenanceStatistics; } } } }

]]>



    
      This section presents a simple but complete example of configuring
      all four entities in , based on the YANG
      module specified in . The example is illustrative
      in nature, but aims to be self-contained, i.e. were it to be executed in
      a real TWAMP implementation it would lead to a correctly configured test
      session. A more elaborated example, which also includes authentication
      parameters, is provided in .

      
        The following configuration example shows a Control-Client with
        clientAdminState enabled. In a real implementation this would permit
        the Control-Client functional entity to initiate TWAMP control
        connections and test sessions.

        
          
   
      True
   

]]>
        

        The following configuration example shows a Control-Client with two
        instances of twampClientCtrlConnection, one called "RouterA" and
        another called "RouterB". Each control connection is to a different
        Server. The control connection named "RouterA" has two test session
        requests. The control connection with name "RouterB" has no test
        session requests.

        
          
   
   
      
         RouterA
         203.0.113.1
         203.0.113.2
         
            Test1
            10.1.1.1
            4000
            10.1.1.2
            5000
            0
         
         
            Test2
            203.0.113.1
            4001
            203.0.113.2
            5001
            0
         
      
	  
      
         RouterB
         203.0.113.1
         203.0.113.3
      
	  
   

]]>
        
      

      
        This configuration example shows a Server with serverAdminState
        enabled, which permits the device to respond to TWAMP control
        connections and test sessions.

        
          

          
   
      True
   

]]>
        

        The following example presents a Server with the control connection
        corresponding to the control connection name (ctrlConnectionName)
        "RouterA" presented in .

        
          
   
   
      
         203.0.113.1
         16341
         203.0.113.2
         862
         active
      
   
   

]]>
        
      

      
        The following configuration example shows a Session-Sender with the
        two test sessions presented earlier in .

        
          
   
   
      
         Test1
         RouterA  // read-only
         900
         
            1
            seconds
         
      
	  
      
         Test2
         RouterA  // read-only
         900
         
            1
            1
            2
            seconds
      	
      
	  
   

]]>
        
      

      
        The following example shows the two Session-Reflector test sessions
        corresponding to the test sessions presented in .

        
          
   
   
       
         1232
         10.1.1.1
         10.1.1.2
         4000
         5000
         
		   203.0.113.1
		 
         
		   16341
		 
         
		   203.0.113.2
		 
         
		   862
		 
         2
         2
         1
         1
      
	  
      
         178943
         203.0.113.1
         192.68.0.2
         4001
         
		   203.0.113.1
		 
         
		   16341
		 
         
		   203.0.113.2
		 
         
		   862
		 
         5001
         21
         21
         20
         20
      
	  
   

]]>
        
		
      
	  
    

	
    
      TBD
    

    
      This document registers a URI in the IETF XML registry . Following the format in ,
      the following registration is requested to be made.

      URI: urn:ietf:params:xml:ns:yang:ietf-twamp

      Registrant Contact: The IPPM WG of the IETF.

      XML: N/A, the requested URI is an XML namespace.

      This document registers a YANG module in the YANG Module Names
      registry .

      name: ietf-twamp

      namespace: urn:ietf:params:xml:ns:yang:ietf-twamp

      prefix: twamp

      reference: RFC XXXX
    

    
      Haoxing Shen contributed to the definition of the YANG module in
      .

      Kostas Pentikousis is 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.



  
    
      

      

      

      

      

      
    

    
      

      

      

      

      

      

      

      

      

      

      

      
        
          Research directions in network service chaining

          
            John, W., Pentikousis, K., et al.
          

          
        

        
      
    

    
      In this section we extend the example presented in  by configuring more fields such as authentication
      parameters, dscp values and so on.

	  
      
        
   
   
      True
	  
      
         0
         0x00000002
      
      
         1
         0x00000001
      
	  
      
         KeyClient1ToRouterA
         secret1
      
      
         KeyForRouterB
         secret2
      
	  
      
         RouterA
         203.0.113.1
         203.0.113.2
         32
         KeyClient1ToRouterA
         1024
         
            Test1
            10.1.1.1
            4000
            10.1.1.2
            5000
            0
            0
            ok
            1232
         
         
            Test2
            203.0.113.1
            4001
            203.0.113.2
            5001
            32
            0
            ok
            178943
         
      
	  
   

]]>
      
	  
	  

	  
      
        
   
   
      True
      1800
      32
      0x00000003
      1024
      256
	  
      
         KeyClient1ToRouterA
         secret1
      
      
         KeyClient10ToRouterA
         secret10
      
	  
      
         203.0.113.1
         16341
         203.0.113.2
         862
         active
         32
         0x00000002
         KeyClient1ToRouterA
         1024
      
	  
   

]]>
      
	  
	  
	  
      
        
   
   
      
         Test1
         RouterA  // read-only
         32
         zero
         900
         
            1
            seconds
         
         Active
         2
         2
         1
         1
      
	  
      
         Test2
         RouterA  // read-only
         32
         random
         900
         
       	   1
            1
            2
            seconds
         
         Active
         21
         21
         20
         20
      
	  
   

]]>
      
	  
	

	
      
        
   
   
      
         1232
         10.1.1.1
         10.1.1.2
         4000
         5000
         
            203.0.113.1
         
         
            16341
         
         
            203.0.113.2
         
         
            862
         
         32
         2
         2
         1
         1
      
	  
      
         178943
         203.0.113.1
         192.68.0.2
         4001
         
            203.0.113.1
         
         
            16341
         
         
            203.0.113.2
         
         
            862
         
         5001
         32
         21
         21
         20
         20
      
	  
   

]]>