TCPM M. Scharf Internet-Draft Hochschule Esslingen Intended status: Standards Track V. Murgai Expires: January 11, 2021 M. Jethanandani Kloud Services July 10, 2020 YANG Model for Transmission Control Protocol (TCP) Configuration draft-scharf-tcpm-yang-tcp-06 Abstract This document specifies a YANG model for TCP on devices that are configured by network management protocols. The YANG model defines a container for all TCP connections and groupings of some of the parameters that can be imported and used in TCP implementations or by other models that need to configure TCP parameters. The model includes definitions from YANG Groupings for TCP Client and TCP Servers (I-D.ietf-netconf-tcp-client-server). The model is NMDA (RFC 8342) compliant. 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 January 11, 2021. Copyright Notice Copyright (c) 2020 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 Scharf, et al. Expires January 11, 2021 [Page 1] Internet-Draft TCP Configuration July 2020 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 2. Requirements Language . . . . . . . . . . . . . . . . . . . . 3 2.1. Note to RFC Editor . . . . . . . . . . . . . . . . . . . 3 3. Model Overview . . . . . . . . . . . . . . . . . . . . . . . 4 3.1. Modeling Scope . . . . . . . . . . . . . . . . . . . . . 4 3.2. Model Design . . . . . . . . . . . . . . . . . . . . . . 5 3.3. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 6 4. TCP YANG Model . . . . . . . . . . . . . . . . . . . . . . . 6 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 5.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 13 5.2. The YANG Module Names Registry . . . . . . . . . . . . . 13 6. Security Considerations . . . . . . . . . . . . . . . . . . . 13 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 13 7.1. Normative References . . . . . . . . . . . . . . . . . . 13 7.2. Informative References . . . . . . . . . . . . . . . . . 15 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 16 Appendix B. Changes compared to previous versions . . . . . . . 16 Appendix C. Examples . . . . . . . . . . . . . . . . . . . . . . 17 C.1. Keepalive Configuration . . . . . . . . . . . . . . . . . 17 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 18 1. Introduction The Transmission Control Protocol (TCP) [RFC0793] is used by many applications in the Internet, including control and management protocols. Therefore, TCP is implemented on network elements that can be configured via network management protocols such as NETCONF [RFC6241] or RESTCONF [RFC8040]. This document specifies a YANG [RFC7950] 1.1 model for configuring TCP on network elements that support YANG data models, and is Network Management Datastore Architecture (NMDA) [RFC8342] compliant. This module defines a container for TCP connection, and includes definitions from YANG Groupings for TCP Clients and TCP Servers [I-D.ietf-netconf-tcp-client-server]. The model has a narrow scope and focuses on fundamental TCP functions and basic statistics. The model can be augmented or updated to address more advanced or implementation-specific TCP features in the future. Scharf, et al. Expires January 11, 2021 [Page 2] Internet-Draft TCP Configuration July 2020 Many protocol stacks on Internet hosts use other methods to configure TCP, such as operating system configuration or policies. Many TCP/IP stacks cannot be configured by network management protocols such as NETCONF [RFC6241] or RESTCONF [RFC8040]. Moreover, many existing TCP/IP stacks do not use YANG data models. Such TCP implementations often have other means to configure the parameters listed in this document, which are outside the scope of this document. This specification is orthogonal to the Management Information Base (MIB) for the Transmission Control Protocol (TCP) [RFC4022]. The basic statistics defined in this document follow the model of the TCP MIB. An TCP Extended Statistics MIB [RFC4898] is also available, but this document does not cover such extended statistics. It is possible also to translate a MIB into a YANG model, for instance using Translation of Structure of Management Information Version 2 (SMIv2) MIB Modules to YANG Modules [RFC6643]. However, this approach is not used in this document, as such a translated model would not be up-to-date. There are other existing TCP-related YANG models, which are othogonal to this specification. Examples are: o TCP header attributes are modeled in other models, such as YANG Data Model for Network Access Control Lists (ACLs) [RFC8519] and Distributed Denial-of-Service Open Thread Signaling (DOTS) Data Channel Specification [I-D.ietf-dots-data-channel]. o TCP-related configuration of a NAT (e.g., NAT44, NAT64, Destination NAT, ...) is defined in A YANG Module for Network Address Translation (NAT) and Network Prefix Translation (NPT) [RFC8512] and A YANG Data Model for Dual-Stack Lite (DS-Lite) [RFC8513]. 2. Requirements Language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "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. 2.1. Note to RFC Editor This document uses several placeholder values throughout the document. Please replace them as follows and remove this note before publication. Scharf, et al. Expires January 11, 2021 [Page 3] Internet-Draft TCP Configuration July 2020 RFC XXXX, where XXXX is the number assigned to this document at the time of publication. 2020-07-10 with the actual date of the publication of this document. 3. Model Overview 3.1. Modeling Scope TCP is implemented on many different system architectures. As a result, there are may different and often implementation-specific ways to configure parameters of the TCP protocol engine. In addition, in many TCP/IP stacks configuration exists for different scopes: o Global configuration: Many TCP implementations have configuration parameters that affect all TCP connections. Typical examples include enabling or disabling optional protocol features. o Interface configuration: It can be useful to use different TCP parameters on different interfaces, e.g., different device ports or IP interfaces. In that case, TCP parameters can be part of the interface configuration. Typical examples are the Maximum Segment Size (MSS) or configuration related to hardware offloading. o Connection parameters: Many implementations have means to influence the behavior of each TCP connection, e.g., on the programming interface used by applications. A typical example are socket options in the socket API, such as disabling the Nagle algorithm by TCP_NODELAY. If an application uses such an interface, it is possible that the configuration of the application or application protocol includes TCP-related parameters. An example is the BGP YANG Model for Service Provider Networks [I-D.ietf-idr-bgp-model]. o Policies: Setting of TCP parameters can also be part of system policies, templates, or profiles. An example would be the preferences defined in An Abstract Application Layer Interface to Transport Services [I-D.ietf-taps-interface]. As a result, there is no ground truth for setting certain TCP parameters, and traditionally different TCP implementation have used different modeling approaches. For instance, one implementation may define a given configuration parameter globally, while another one uses per-interface settings, and both approaches work well for the corresponding use cases. Also, different systems may use different default values. In addition, TCP can be implemented in different Scharf, et al. Expires January 11, 2021 [Page 4] Internet-Draft TCP Configuration July 2020 ways and design choices by the protocol engine often affect configuration options. Nonetheless, a number of TCP stack parameters require configuration by YANG models. This document therefore defines a minimal YANG model with fundamental parameters directly following from TCP standards. An important use case is the TCP configuration on network elements such as routers, which often use YANG data models. The model therefore specifies TCP parameters that are important on such TCP stacks. A typical example is the support of TCP-AO [RFC5925]. TCP- AO is increasingly supported on routers to secure routing protocols such as BGP. In that case, TCP-AO configuration is required on routers. Given an installed base, the model also allows enabling of the legacy TCP MD5 [RFC2385] signature option. As the TCP MD5 signature option is obsoleted by TCP-AO, it is strongly RECOMMENDED to use TCP-AO. Similar to the TCP MIB [RFC4022], this document also specifies basic statistics and a TCP connection table. o Statistics: Counters for the number of active/passive opens, sent and received segments, errors, and possibly other detailed debugging information o TCP connection table: Access to status information for all TCP connections This allows implementations of TCP MIB [RFC4022] to migrate to the YANG model defined in this memo. 3.2. Model Design The YANG model defined in this document includes definitions from the YANG Groupings for TCP Clients and TCP Servers [I-D.ietf-netconf-tcp-client-server]. Similar to that model, this specification defines YANG groupings. This allows reuse of these groupings in different YANG data models. It is intended that these groupings will be used either standalone or for TCP-based protocols as part of a stack of protocol-specific configuration models. An example could be the BGP YANG Model for Service Provider Networks [I-D.ietf-idr-bgp-model]. Scharf, et al. Expires January 11, 2021 [Page 5] Internet-Draft TCP Configuration July 2020 3.3. Tree Diagram This section provides a abridged tree diagram for the YANG module defined in this document. Annotations used in the diagram are defined in YANG Tree Diagrams [RFC8340]. module: ietf-tcp +--rw tcp! +--rw connections | ... +--rw server {server}? | ... +--rw client {client}? | ... +--ro statistics {statistics}? ... 4. TCP YANG Model file "ietf-tcp@2020-07-10.yang" module ietf-tcp { yang-version "1.1"; namespace "urn:ietf:params:xml:ns:yang:ietf-tcp"; prefix "tcp"; import ietf-yang-types { prefix "yang"; reference "RFC 6991: Common YANG Data Types."; } import ietf-tcp-client { prefix "tcpc"; } import ietf-tcp-server { prefix "tcps"; } import ietf-tcp-common { prefix "tcpcmn"; } import ietf-inet-types { prefix "inet"; } organization "IETF TCPM Working Group"; contact Scharf, et al. Expires January 11, 2021 [Page 6] Internet-Draft TCP Configuration July 2020 "WG Web: WG List: Authors: Michael Scharf (michael.scharf at hs-esslingen dot de) Vishal Murgai (vmurgai at gmail dot com) Mahesh Jethanandani (mjethanandani at gmail dot com)"; description "This module focuses on fundamental and standard TCP functions that widely implemented. The model can be augmented to address more advanced or implementation specific TCP features."; revision "2020-07-10" { description "Initial Version"; reference "RFC XXX, TCP Configuration."; } // Features feature server { description "TCP Server configuration supported."; } feature client { description "TCP Client configuration supported."; } feature statistics { description "This implementation supports statistics reporting."; } // TCP-AO Groupings grouping ao { leaf enable-ao { type boolean; default "false"; description "Enable support of TCP-Authentication Option (TCP-AO)."; } leaf send-id { type uint8 { range "0..255"; Scharf, et al. Expires January 11, 2021 [Page 7] Internet-Draft TCP Configuration July 2020 } must "../enable-ao = 'true'"; description "The SendID is inserted as the KeyID of the TCP-AO option of outgoing segments."; reference "RFC 5925: The TCP Authentication Option."; } leaf recv-id { type uint8 { range "0..255"; } must "../enable-ao = 'true'"; description "The RecvID is matched against the TCP-AO KeyID of incoming segments."; reference "RFC 5925: The TCP Authentication Option."; } leaf include-tcp-options { type boolean; must "../enable-ao = 'true'"; description "Include TCP options in HMAC calculation."; } leaf accept-ao-mismatch { type boolean; must "../enable-ao = 'true'"; description "Accept packets with HMAC mismatch."; } description "Authentication Option (AO) for TCP."; reference "RFC 5925: The TCP Authentication Option."; } // MD5 grouping grouping md5 { description "Grouping for use in authenticating TCP sessions using MD5."; reference "RFC 2385: Protection of BGP Sessions via the TCP MD5 Signature."; Scharf, et al. Expires January 11, 2021 [Page 8] Internet-Draft TCP Configuration July 2020 leaf enable-md5 { type boolean; default "false"; description "Enable support of MD5 to authenticate a TCP session."; } } // TCP configuration container tcp { presence "The container for TCP configuration."; description "TCP container."; container connections { list connection { key "local-address remote-address local-port remote-port"; leaf local-address { type inet:ip-address; description "Local address that forms the connection identifier."; } leaf remote-address { type inet:ip-address; description "Remote address that forms the connection identifier."; } leaf local-port { type inet:port-number; description "Local TCP port that forms the connection identifier."; } leaf remote-port { type inet:port-number; description "Remote TCP port that forms the connection identifier."; } container common { uses tcpcmn:tcp-common-grouping; choice authentication { Scharf, et al. Expires January 11, 2021 [Page 9] Internet-Draft TCP Configuration July 2020 case ao { uses ao; description "Use TCP-AO to secure the connection."; } case md5 { uses md5; description "Use TCP-MD5 to secure the connection."; } description "Choice of how to secure the TCP connection."; } description "Common definitions of TCP configuration. This includes parameters such as how to secure the connection, that can be part of either the client or server."; } description "Connection related parameters."; } description "A container of all TCP connections."; } container server { if-feature server; uses tcps:tcp-server-grouping; description "Definitions of TCP server configuration."; } container client { if-feature client; uses tcpc:tcp-client-grouping; description "Definitions of TCP client configuration."; } container statistics { if-feature statistics; config false; leaf active-opens { type yang:counter32; description "The number of times that TCP connections have made a direct Scharf, et al. Expires January 11, 2021 [Page 10] Internet-Draft TCP Configuration July 2020 transition to the SYN-SENT state from the CLOSED state."; } leaf passive-opens { type yang:counter32; description "The number of times TCP connections have made a direct transition to the SYN-RCVD state from the LISTEN state."; } leaf attempt-fails { type yang:counter32; description "The number of times that TCP connections have made a direct transition to the CLOSED state from either the SYN-SENT state or the SYN-RCVD state, plus the number of times that TCP connections have made a direct transition to the LISTEN state from the SYN-RCVD state."; } leaf establish-resets { type yang:counter32; description "The number of times that TCP connections have made a direct transition to the CLOSED state from either the ESTABLISHED state or the CLOSE-WAIT state."; } leaf currently-established { type yang:gauge32; description "The number of TCP connections for which the current state is either ESTABLISHED or CLOSE-WAIT."; } leaf in-segments { type yang:counter64; description "The total number of segments received, including those received in error. This count includes segments received on currently established connections."; } leaf out-segments { type yang:counter64; description "The total number of segments sent, including those on current connections but excluding those containing only Scharf, et al. Expires January 11, 2021 [Page 11] Internet-Draft TCP Configuration July 2020 retransmitted octets."; } leaf retransmitted-segments { type yang:counter32; description "The total number of segments retransmitted; that is, the number of TCP segments transmitted containing one or more previously transmitted octets."; } leaf in-errors { type yang:counter32; description "The total number of segments received in error (e.g., bad TCP checksums)."; } leaf out-resets { type yang:counter32; description "The number of TCP segments sent containing the RST flag."; } action reset { description "Reset statistics action command."; input { leaf reset-at { type yang:date-and-time; description "Time when the reset action needs to be executed."; } } output { leaf reset-finished-at { type yang:date-and-time; description "Time when the reset action command completed."; } } } description "Statistics across all connections."; } } } Scharf, et al. Expires January 11, 2021 [Page 12] Internet-Draft TCP Configuration July 2020 5. IANA Considerations 5.1. The IETF XML Registry This document registers two URIs in the "ns" subregistry of the IETF XML Registry [RFC3688]. Following the format in IETF XML Registry [RFC3688], the following registrations are requested: URI: urn:ietf:params:xml:ns:yang:ietf-tcp Registrant Contact: The TCPM WG of the IETF. XML: N/A, the requested URI is an XML namespace. 5.2. The YANG Module Names Registry This document registers a YANG modules in the YANG Module Names registry YANG - A Data Modeling Language [RFC6020]. Following the format in YANG - A Data Modeling Language [RFC6020], the following registrations are requested: name: ietf-tcp namespace: urn:ietf:params:xml:ns:yang:ietf-tcp prefix: tcp reference: RFC XXXX 6. Security Considerations The YANG module specified in this document defines a schema for data that is designed to be accessed via network management protocols such as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer is the secure transport layer, and the mandatory-to-implement secure transport is Secure Shell (SSH) described in Using the NETCONF protocol over SSH [RFC6242]. The lowest RESTCONF layer is HTTPS, and the mandatory-to-implement secure transport is TLS [RFC8446]. The Network Configuration Access Control Model (NACM) [RFC8341] provides the means to restrict access for particular NETCONF or RESTCONF users to a preconfigured subset of all available NETCONF or RESTCONF protocol operations and content. 7. References 7.1. Normative References Scharf, et al. Expires January 11, 2021 [Page 13] Internet-Draft TCP Configuration July 2020 [I-D.ietf-netconf-tcp-client-server] Watsen, K. and M. Scharf, "YANG Groupings for TCP Clients and TCP Servers", draft-ietf-netconf-tcp-client-server-06 (work in progress), June 2020. [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, RFC 793, DOI 10.17487/RFC0793, September 1981, . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC2385] Heffernan, A., "Protection of BGP Sessions via the TCP MD5 Signature Option", RFC 2385, DOI 10.17487/RFC2385, August 1998, . [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, DOI 10.17487/RFC3688, January 2004, . [RFC5925] Touch, J., Mankin, A., and R. Bonica, "The TCP Authentication Option", RFC 5925, DOI 10.17487/RFC5925, June 2010, . [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, . [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", RFC 7950, DOI 10.17487/RFC7950, August 2016, . [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, . Scharf, et al. Expires January 11, 2021 [Page 14] Internet-Draft TCP Configuration July 2020 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, . [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration Access Control Model", STD 91, RFC 8341, DOI 10.17487/RFC8341, March 2018, . [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., and R. Wilton, "Network Management Datastore Architecture (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, . [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, . 7.2. Informative References [I-D.ietf-dots-data-channel] Boucadair, M. and T. Reddy.K, "Distributed Denial-of- Service Open Threat Signaling (DOTS) Data Channel Specification", draft-ietf-dots-data-channel-31 (work in progress), July 2019. [I-D.ietf-idr-bgp-model] Jethanandani, M., Patel, K., Hares, S., and J. Haas, "BGP YANG Model for Service Provider Networks", draft-ietf-idr- bgp-model-09 (work in progress), June 2020. [I-D.ietf-taps-interface] Trammell, B., Welzl, M., Enghardt, T., Fairhurst, G., Kuehlewind, M., Perkins, C., Tiesel, P., Wood, C., and T. Pauly, "An Abstract Application Layer Interface to Transport Services", draft-ietf-taps-interface-06 (work in progress), March 2020. [RFC4022] Raghunarayan, R., Ed., "Management Information Base for the Transmission Control Protocol (TCP)", RFC 4022, DOI 10.17487/RFC4022, March 2005, . Scharf, et al. Expires January 11, 2021 [Page 15] Internet-Draft TCP Configuration July 2020 [RFC4898] Mathis, M., Heffner, J., and R. Raghunarayan, "TCP Extended Statistics MIB", RFC 4898, DOI 10.17487/RFC4898, May 2007, . [RFC6643] Schoenwaelder, J., "Translation of Structure of Management Information Version 2 (SMIv2) MIB Modules to YANG Modules", RFC 6643, DOI 10.17487/RFC6643, July 2012, . [RFC8512] Boucadair, M., Ed., Sivakumar, S., Jacquenet, C., Vinapamula, S., and Q. Wu, "A YANG Module for Network Address Translation (NAT) and Network Prefix Translation (NPT)", RFC 8512, DOI 10.17487/RFC8512, January 2019, . [RFC8513] Boucadair, M., Jacquenet, C., and S. Sivakumar, "A YANG Data Model for Dual-Stack Lite (DS-Lite)", RFC 8513, DOI 10.17487/RFC8513, January 2019, . [RFC8519] Jethanandani, M., Agarwal, S., Huang, L., and D. Blair, "YANG Data Model for Network Access Control Lists (ACLs)", RFC 8519, DOI 10.17487/RFC8519, March 2019, . Appendix A. Acknowledgements Michael Scharf was supported by the StandICT.eu project, which is funded by the European Commission under the Horizon 2020 Programme. The following persons have contributed to this document by reviews: Mohamed Boucadair Appendix B. Changes compared to previous versions Changes compared to draft-scharf-tcpm-yang-tcp-04 o Removed congestion control o Removed global stack parameters Changes compared to draft-scharf-tcpm-yang-tcp-03 o Updated TCP-AO grouping o Added congestion control Changes compared to draft-scharf-tcpm-yang-tcp-02 Scharf, et al. Expires January 11, 2021 [Page 16] Internet-Draft TCP Configuration July 2020 o Initial proposal of a YANG model including base configuration parameters, TCP-AO configuration, and a connection list o Editorial bugfixes and outdated references reported by Mohamed Boucadair o Additional co-author Mahesh Jethanandani Changes compared to draft-scharf-tcpm-yang-tcp-01 o Alignment with [I-D.ietf-netconf-tcp-client-server] o Removing backward-compatibility to the TCP MIB o Additional co-author Vishal Murgai Changes compared to draft-scharf-tcpm-yang-tcp-00 o Editorial improvements Appendix C. Examples C.1. Keepalive Configuration This particular example demonstrates how both a particular connection can be configured for keepalives. Scharf, et al. Expires January 11, 2021 [Page 17] Internet-Draft TCP Configuration July 2020 192.168.1.1 192.168.1.2 1025 80 5 5 10 192.168.1.1 192.168.1.2 Authors' Addresses Michael Scharf Hochschule Esslingen - University of Applied Sciences Flandernstr. 101 Esslingen 73732 Germany Email: michael.scharf@hs-esslingen.de Scharf, et al. Expires January 11, 2021 [Page 18] Internet-Draft TCP Configuration July 2020 Vishal Murgai Email: vmurgai@gmail.com Mahesh Jethanandani Kloud Services Email: mjethanandani@gmail.com Scharf, et al. Expires January 11, 2021 [Page 19]