IPPM T. Zhou, Ed. Internet-Draft J. Guichard Intended status: Standards Track Huawei Expires: September 5, 2018 F. Brockners S. Raghavan Cisco Systems March 4, 2018 A YANG Data Model for In-Situ OAM draft-zhou-ippm-ioam-yang-00 Abstract In-situ Operations, Administration, and Maintenance (IOAM) records operational and telemetry information in user packets while the packets traverse a path between two points in the network. This document defines a YANG module for the IOAM function. Requirements 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 RFC 2119 [RFC2119]. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. 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 September 5, 2018. Copyright Notice Copyright (c) 2018 IETF Trust and the persons identified as the document authors. All rights reserved. Zhou, Ed., et al. Expires September 5, 2018 [Page 1] Internet-Draft YANG Model for IOAM March 2018 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 carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 3 2. Design of the IOAM YANG Data Model . . . . . . . . . . . . . 3 2.1. Profiles . . . . . . . . . . . . . . . . . . . . . . . . 3 2.2. Preallocated Tracing Profile . . . . . . . . . . . . . . 4 2.3. Incremental Tracing Profile . . . . . . . . . . . . . . . 5 2.4. Proof of Transit Profile . . . . . . . . . . . . . . . . 5 2.5. Edge to Edge Profile . . . . . . . . . . . . . . . . . . 5 3. IOAM YANG Module . . . . . . . . . . . . . . . . . . . . . . 6 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 5. Security Considerations . . . . . . . . . . . . . . . . . . . 15 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 15 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 15 7.1. Normative References . . . . . . . . . . . . . . . . . . 15 7.2. Informative References . . . . . . . . . . . . . . . . . 16 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 17 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 17 1. Introduction In-situ Operations, Administration, and Maintenance (IOAM) [I-D.ietf-ippm-ioam-data] records OAM information within user packets while the packets traverse a network. The data types and data formats for IOAM data records have been defined in [I-D.ietf-ippm-ioam-data]. The IOAM data can be embedded in many protocol encapsulations such as Network Services Header, Segment Routing, and IPv6 [I-D.brockners-inband-oam-transport]. This document defines a data model for IOAM capabilities using the YANG data modeling language [RFC6020][RFC7950]. This YANG model supports all the three categories of IOAM data, which are Tracing Option, Proof of Transit Option, and Edge-to-Edge Option. Zhou, Ed., et al. Expires September 5, 2018 [Page 2] Internet-Draft YANG Model for IOAM March 2018 1.1. Tree Diagrams The meaning of the symbols in these diagrams is as follows: o Brackets "[" and "]" enclose list keys. o Curly braces "{" and "}" contain names of optional features that make the corresponding node conditional. o Abbreviations before data node names: "rw" means configuration (read-write), "ro" state data (read-only). o Symbols after data node names: "?" means an optional node, "!" a container with presence, and "*" denotes a "list" or "leaf-list". o Parentheses enclose choice and case nodes, and case nodes are also marked with a colon (":"). o Ellipsis ("...") stands for contents of subtrees that are not shown. 2. Design of the IOAM YANG Data Model 2.1. Profiles The IOAM model is organized as list of profiles as shown in the following figure. Each profile associates with one flow and the corresponding IOAM information. +--rw ioam +--rw ioam-profiles +--rw enabled? boolean +--rw ioam-profile* [profile-name] +--rw profile-name string +--rw filter | +--rw filter-type? ioam-filter-type | +--rw acl-name? -> /acl:access-lists/acl/name +--rw protocol-type? ioam-protocol-type +--rw incremental-tracing-profile | ... +--rw preallocated-tracing-profile | ... +--rw pot-profile | ... +--rw e2e-profile ... Zhou, Ed., et al. Expires September 5, 2018 [Page 3] Internet-Draft YANG Model for IOAM March 2018 The "filter" is used to identify a flow, where the IOAM profile can apply. There may be multiple filter types. ACL is the default one. The IOAM data can be encapsulated into multiple protocols, e.g., IPv6, Geneve,VxLAN-GPE. The "protocol-type" is used to indicate where the IOAM is applied. For example, if the protocol-type is IPv6, the IOAM ingress node will encapsulate the associated flow with the IPv6-IOAM [I-D.brockners-inband-oam-transport] format. IOAM data includes three usage options with four types data, i.e., incremental tracing data, preallocated tracing data, prove of transit data and end to end data. In practice, multiple IOAM data types can be encapsulated into the same IOAM header. 2.2. Preallocated Tracing Profile The IOAM tracing data is expected to be collected at every node that a packet traverses to ensure visibility into the entire path a packet takes within an IOAM domain. The preallocated tracing option will create pre-allocated space for each node to populate its information . The "preallocated-tracing-profile" contains the detailed information for the preallocated tracing data. It's only valid when the "enable-preallocated-tracing-option" is set to true. The information includes: o enabled: indicates whether the preallocated tracing profile is enabled. o node-action: indicates the operation (e.g., encapsulate IOAM header, transit the IOAM data, or decapsulate IOAM header) applied to the dedicated flow. o trace-type: indicates the per-hop data to be captured by the IOAM enabled nodes and included in the node data list. o Loopback mode is used to send a copy of a packet back towards the source. +--rw preallocated-tracing-profile +--rw enabled? boolean +--rw node-action? ioam-node-action +--rw trace-type? ioam-trace-types +--rw enable-loopback-mode? boolean Zhou, Ed., et al. Expires September 5, 2018 [Page 4] Internet-Draft YANG Model for IOAM March 2018 2.3. Incremental Tracing Profile The incremental tracing option contains a variable node data fields where each node allocates and pushes its node data immediately following the option header. The "incremental-tracing-profile" contains the detailed information for the incremental tracing data. It's only valid when the "enable-incremental-tracing-option" is set to true. The detailed information is the same as the Preallocated Tracing Profile, but with one more variable, "max-length", which restricts the length of the IOAM header. +--rw incremental-tracing-profile +--rw enabled? boolean +--rw node-action? ioam-node-action +--rw trace-type? ioam-trace-types +--rw enable-loopback-mode? boolean +--rw max-length? uint32 2.4. Proof of Transit Profile The IOAM Proof of Transit data is to support the path or service function chain verification use cases. The "pot-profile" contains the detailed information for the prove of transit data. It's only valid when the "enable-pot-option" is set to true. The detailed information are described in [I-D.brockners-proof-of-transit]. +--rw pot-profile +--rw enabled? boolean +--rw active-profile-index? pot:profile-index-range +--rw pot-profile-list* [pot-profile-index] +--rw pot-profile-index profile-index-range +--rw prime-number uint64 +--rw secret-share uint64 +--rw public-polynomial uint64 +--rw lpc uint64 +--rw validator? boolean +--rw validator-key? uint64 +--rw bitmask? uint64 2.5. Edge to Edge Profile The IOAM edge to edge option is to carry data that is added by the IOAM encapsulating node and interpreted by IOAM decapsulating node. The "e2e-profile" contains the detailed information for the edge to edge data. It's only valid when the "enable-e2e-option" is set to true. The detailed information includes: o enabled: indicates whether the edge to edge profile is enabled. Zhou, Ed., et al. Expires September 5, 2018 [Page 5] Internet-Draft YANG Model for IOAM March 2018 o node-action is the same semantic as in Section 2.2. o e2e-type indicates data to be carried from the ingress IOAM node to the egress IOAM node. +--rw e2e-profile +--rw enabled? boolean +--rw node-action? ioam-node-action +--rw e2e-type? ioam-e2e-types 3. IOAM YANG Module file "ietf-ioam@2018-03-04.yang" module ietf-ioam { yang-version 1.1; namespace "urn:ietf:params:xml:ns:yang:ietf-ioam"; prefix "ioam"; import ietf-pot-profile { prefix "pot"; } import ietf-access-control-list { prefix "acl"; } organization "IETF IPPM (IP Performance Metrics) Working Group"; contact "WG Web: WG List: Editor: zhoutianran@huawei.com"; description "This YANG module specifies a vendor-independent data model for the in Situ OAM (iOAM)."; revision 2018-03-04 { description "Initial revision."; reference "draft-song-ippm-ioam-yang"; } identity base-filter { description "Base identity to represent a filter. A filter is used to specify the flow to apply the iOAM profile. "; } Zhou, Ed., et al. Expires September 5, 2018 [Page 6] Internet-Draft YANG Model for IOAM March 2018 identity acl-filter { base base-filter; description "Apply ACL rule to specify the flow."; } identity base-protocol { description "Base identity to represent the carrier protocol. It's used to indicate what layer and protocol the iOAM data is embedded."; } identity ipv6-protocol { base base-protocol; description "The described iOAM data is embedded in ipv6 protocol."; } identity base-node-action { description "Base identity to represent the node actions. It's used to indicate what action the node will take."; } identity encapsulate { base base-node-action; description "indicate the node is to encapsulate the iOAM packet"; } identity transit { base base-node-action; description "indicate the node is to transit the iOAM packet"; } identity decapsulate { base base-node-action; description "indicate the node is to decapsulate the iOAM packet"; } typedef ioam-filter-type { type identityref { base base-filter; } description "Specifies a known type of filter."; Zhou, Ed., et al. Expires September 5, 2018 [Page 7] Internet-Draft YANG Model for IOAM March 2018 } typedef ioam-protocol-type { type identityref { base base-protocol; } description "Specifies a known type of carrier protocol for the iOAM data."; } typedef ioam-node-action { type identityref { base base-node-action; } description "Specifies a known type of node action."; } typedef ioam-trace-types { type bits { bit ioam-hop-lim-node-id { position 0; description "When set indicates presence of Hop_Lim and node_id in the node data."; } bit ioam-if-id { position 1; description "When set indicates presence of ingress_if_id and egress_if_id in the node data."; } bit ioam-timestamp-seconds { position 2; description "When set indicates presence of time stamp seconds in the node data."; } bit ioam-timestamp-nanoseconds { position 3; description "When set indicates presence of time stamp nanoseconds in the node data."; } bit ioam-transit-delay { position 4; description "When set indicates presence of transit delay in the node Zhou, Ed., et al. Expires September 5, 2018 [Page 8] Internet-Draft YANG Model for IOAM March 2018 data."; } bit ioam-app-data { position 5; description "When set indicates presence of app_data in the node data."; } bit ioam-queue-depth { position 6; description "When set indicates presence of queue depth in the node data."; } bit ioam-opaque-state-snapshot { position 7; description "When set indicates presence of variable length Opaque State Snapshot field."; } bit ioam-hop-lim-node-id-wide { position 8; description "When set indicates presence of Hop_Lim and node_id wide in the node data."; } bit ioam-if-id-wide { position 9; description "When set indicates presence of ingress_if_id and egress_if_id wide in the node data."; } bit app-data-wide { position 10; description "When set indicates presence of app_data wide in the node data."; } } description "A 16-bit identifier which specifies which data types are used in this node data list."; } typedef ioam-pot-types { type bits { bit ioam-bytes-16 { position 0; description Zhou, Ed., et al. Expires September 5, 2018 [Page 9] Internet-Draft YANG Model for IOAM March 2018 "POT data is a 16 Octet field"; } } description "7-bit identifier of a particular POT variant that dictates the POT data that is included."; } typedef ioam-e2e-types { type bits { bit ioam-seq-num { position 0; description "A 64-bit sequence number added to a specific tube which is used to identify packet loss and reordering for that tube."; } } description "8-bit identifier of a particular in situ OAM E2E variant."; } grouping ioam-filter { description "A grouping for iOAM filter definition"; leaf filter-type { type ioam-filter-type; description "filter type"; } leaf acl-name { when "../filter-type = 'acl-filter'"; type leafref { path "/acl:access-lists/acl:acl/acl:name"; } description "Access Control List name."; } } grouping ioam-incremental-tracing-profile { description "A grouping for incremental tracing profile."; leaf node-action { type ioam-node-action; description "node action"; } Zhou, Ed., et al. Expires September 5, 2018 [Page 10] Internet-Draft YANG Model for IOAM March 2018 leaf trace-type { when "../node-action = 'encapsulate'"; type ioam-trace-types; description "The trace type is only defined at the encapsulation node."; } leaf enable-loopback-mode { when "../node-action = 'encapsulate'"; type boolean; default false; description "Loopback mode is used to send a copy of a packet back towards the source. The loopback mode is only defined at the encapsulation node."; } leaf max-length { when "../node-action = 'encapsulate'"; type uint32; description "This field specifies the maximum length of the node data list in octets. The max-length is only defined at the encapsulation node. And it's only used for the incremental tracing mode."; } } grouping ioam-preallocated-tracing-profile { description "A grouping for incremental tracing profile."; leaf node-action { type ioam-node-action; description "node action"; } leaf trace-type { when "../node-action = 'encapsulate'"; type ioam-trace-types; description "The trace type is only defined at the encapsulation node."; } leaf enable-loopback-mode { when "../node-action = 'encapsulate'"; type boolean; default false; Zhou, Ed., et al. Expires September 5, 2018 [Page 11] Internet-Draft YANG Model for IOAM March 2018 description "Loopback mode is used to send a copy of a packet back towards the source. The loopback mode is only defined at the encapsulation node."; } } grouping ioam-e2e-profile { description "A grouping for tracing profile."; leaf node-action { type ioam-node-action; description "indicate how the node act for this profile"; } leaf e2e-type { when "../node-action = 'encapsulate'"; type ioam-e2e-types; description "The e2e type is only defined at the encapsulation node."; } } grouping ioam-admin-config { description "IOAM top-level administrative configuration."; leaf enabled { type boolean; default false; description "When true, IOAM configuration is enabled for the system."; } } container ioam { description "iOAM top level container"; container ioam-profiles { description "Contains a list of iOAM profiles."; uses ioam-admin-config; list ioam-profile { key "profile-name"; Zhou, Ed., et al. Expires September 5, 2018 [Page 12] Internet-Draft YANG Model for IOAM March 2018 ordered-by user; description "A list of iOAM profiles that configured on the node."; leaf profile-name { type string; description "Unique identifier for each iOAM profile"; } container filter { uses ioam-filter; description "The filter which is used to indicate the flow to apply iOAM."; } leaf protocol-type { type ioam-protocol-type; description "This item is used to indicate the carrier protocol where the iOAM is applied."; } container incremental-tracing-profile { description "describe the profile for incremental tracing option"; leaf enabled { type boolean; default false; description "When true, apply incremental tracing option to the specified flow identified by the filter."; } uses ioam-incremental-tracing-profile; } container preallocated-tracing-profile { description "describe the profile for preallocated tracing option"; leaf enabled { type boolean; default false; description "When true, apply preallocated tracing option to the Zhou, Ed., et al. Expires September 5, 2018 [Page 13] Internet-Draft YANG Model for IOAM March 2018 specified flow identified by the following filter."; } uses ioam-preallocated-tracing-profile; } container pot-profile { description "describe the profile for pot option"; leaf enabled { type boolean; default false; description "When true, apply Proof of Transit option to the specified flow identified by the following filter."; } leaf active-profile-index { type pot:profile-index-range; description "Proof of transit profile index that is currently active. Will be set in the first hop of the path or chain. Other nodes will not use this field."; } uses pot:pot-profile; } container e2e-profile { description "describe the profile for e2e option"; leaf enabled { type boolean; default false; description "When true, apply End to end option to the specified flow identified by the following filter."; } uses ioam-e2e-profile; } } } } } Zhou, Ed., et al. Expires September 5, 2018 [Page 14] Internet-Draft YANG Model for IOAM March 2018 4. IANA Considerations RFC Ed.: In this section, replace all occurrences of 'XXXX' with the actual RFC number (and remove this note). This document requests IANA to register the following URI in the "IETF XML Registry" [RFC3688]: URI: urn:ietf:params:xml:ns:yang:ietf-ioam Registrant Contact: The IESG. XML: N/A; the requested URI is an XML namespace. This document requests IANA to register the following YANG module in the "YANG Module Names" registry [RFC7950]. name: ietf-ioam namespace: urn:ietf:params:xml:ns:yang:ietf-ioam prefix: nat reference: RFC XXXX 5. Security Considerations The YANG module defined in this memo is designed to be accessed via the NETCONF protocol [RFC6241]. The lowest NETCONF layer is the secure transport layer and the support of SSH is mandatory to implement secure transport[RFC6242]. The NETCONF access control model [RFC6536] provides means to restrict access by some users to a pre-configured subset of all available NETCONF protocol operations and data. All data nodes defined in the YANG module which can be created, modified and deleted (i.e., config true, which is the default). These data nodes are considered sensitive. Write operations (e.g., edit-config) applied to these data nodes without proper protection can negatively affect network operations. 6. Acknowledgements 7. References 7.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, . [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, DOI 10.17487/RFC3688, January 2004, . Zhou, Ed., et al. Expires September 5, 2018 [Page 15] Internet-Draft YANG Model for IOAM March 2018 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", RFC 6020, DOI 10.17487/RFC6020, October 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, . [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, . [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration Protocol (NETCONF) Access Control Model", RFC 6536, DOI 10.17487/RFC6536, March 2012, . [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", RFC 7950, DOI 10.17487/RFC7950, August 2016, . 7.2. Informative References [I-D.brockners-inband-oam-transport] Brockners, F., Bhandari, S., Govindan, V., Pignataro, C., Gredler, H., Leddy, J., Youell, S., Mizrahi, T., Mozes, D., Lapukhov, P., and R. Chang, "Encapsulations for In- situ OAM Data", draft-brockners-inband-oam-transport-05 (work in progress), July 2017. [I-D.brockners-proof-of-transit] Brockners, F., Bhandari, S., Dara, S., Pignataro, C., Leddy, J., Youell, S., Mozes, D., and T. Mizrahi, "Proof of Transit", draft-brockners-proof-of-transit-04 (work in progress), October 2017. [I-D.ietf-ippm-ioam-data] Brockners, F., Bhandari, S., Pignataro, C., Gredler, H., Leddy, J., Youell, S., Mizrahi, T., Mozes, D., Lapukhov, P., Chang, R., and d. daniel.bernier@bell.ca, "Data Fields for In-situ OAM", draft-ietf-ippm-ioam-data-01 (work in progress), October 2017. Zhou, Ed., et al. Expires September 5, 2018 [Page 16] Internet-Draft YANG Model for IOAM March 2018 Appendix A. Examples TBD Authors' Addresses Tianran Zhou Huawei 156 Beiqing Rd. Beijing 100095 China Phone: 15810236238 Email: zhoutianran@huawei.com Jim Guichard Huawei USA Email: james.n.guichard@huawei.com Frank Brockners Cisco Systems Hansaallee 249, 3rd Floor DUESSELDORF, NORDRHEIN-WESTFALEN 40549 Germany Email: fbrockne@cisco.com Srihari Raghavan Cisco Systems Tril Infopark Sez, Ramanujan IT City Neville Block, 2nd floor, Old Mahabalipuram Road Chennai, Tamil Nadu 600113 India Email: srihari@cisco.com Zhou, Ed., et al. Expires September 5, 2018 [Page 17]