idnits 2.17.1 draft-kwatsen-netconf-tcp-client-server-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 113 has weird spacing: '...address ine...' == Line 122 has weird spacing: '...address ine...' == Line 241 has weird spacing: '...te peer to co...' == Line 334 has weird spacing: '...address ine...' -- The document date (March 9, 2019) is 1867 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) No issues found here. Summary: 0 errors (**), 0 flaws (~~), 5 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF Working Group K. Watsen 3 Internet-Draft Watsen Networks 4 Intended status: Standards Track March 9, 2019 5 Expires: September 10, 2019 7 YANG Groupings for TCP Clients and TCP Servers 8 draft-kwatsen-netconf-tcp-client-server-00 10 Abstract 12 This document defines two YANG modules: the first defines a grouping 13 for configuring a generic TCP client, and the second defines a 14 grouping for configuring a generic TCP server. It is intended that 15 these groupings will be used by applications using the TCP protocol. 17 Editorial Note (To be removed by RFC Editor) 19 This draft contains many placeholder values that need to be replaced 20 with finalized values at the time of publication. This note 21 summarizes all of the substitutions that are needed. No other RFC 22 Editor instructions are specified elsewhere in this document. 24 Artwork in this document contains placeholder values for the date of 25 publication of this draft. Please apply the following replacement: 27 o "2019-03-09" --> the publication date of this draft 29 The following Appendix section is to be removed prior to publication: 31 o Appendix A. Change Log 33 Status of This Memo 35 This Internet-Draft is submitted in full conformance with the 36 provisions of BCP 78 and BCP 79. 38 Internet-Drafts are working documents of the Internet Engineering 39 Task Force (IETF). Note that other groups may also distribute 40 working documents as Internet-Drafts. The list of current Internet- 41 Drafts is at https://datatracker.ietf.org/drafts/current/. 43 Internet-Drafts are draft documents valid for a maximum of six months 44 and may be updated, replaced, or obsoleted by other documents at any 45 time. It is inappropriate to use Internet-Drafts as reference 46 material or to cite them other than as "work in progress." 48 This Internet-Draft will expire on September 10, 2019. 50 Copyright Notice 52 Copyright (c) 2019 IETF Trust and the persons identified as the 53 document authors. All rights reserved. 55 This document is subject to BCP 78 and the IETF Trust's Legal 56 Provisions Relating to IETF Documents 57 (https://trustee.ietf.org/license-info) in effect on the date of 58 publication of this document. Please review these documents 59 carefully, as they describe your rights and restrictions with respect 60 to this document. Code Components extracted from this document must 61 include Simplified BSD License text as described in Section 4.e of 62 the Trust Legal Provisions and are provided without warranty as 63 described in the Simplified BSD License. 65 Table of Contents 67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 68 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 69 3. The TCP Client Model . . . . . . . . . . . . . . . . . . . . 3 70 3.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 3 71 3.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 3 72 3.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 4 73 4. The TCP Server Model . . . . . . . . . . . . . . . . . . . . 7 74 4.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 7 75 4.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 8 76 4.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 8 77 5. Security Considerations . . . . . . . . . . . . . . . . . . . 11 78 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 79 6.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 12 80 6.2. The YANG Module Names Registry . . . . . . . . . . . . . 13 81 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 13 82 7.1. Normative References . . . . . . . . . . . . . . . . . . 13 83 7.2. Informative References . . . . . . . . . . . . . . . . . 14 84 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 14 86 1. Introduction 88 This document defines two YANG 1.1 [RFC7950] modules: the first 89 defines a grouping for configuring a generic TCP client, and the 90 second defines a grouping for configuring a generic TCP server. It 91 is intended that these groupings will be used by applications using 92 the TCP protocol. For instance, these groupings could help define 93 the configuration module for an SSH, TLS, or HTTP based application. 95 2. Terminology 97 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 98 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 99 "OPTIONAL" in this document are to be interpreted as described in BCP 100 14 [RFC2119] [RFC8174] when, and only when, they appear in all 101 capitals, as shown here. 103 3. The TCP Client Model 105 3.1. Tree Diagram 107 This section provides a tree diagram [RFC8340] for the "ietf-tcp- 108 client" module. 110 module: ietf-tcp-client 112 grouping tcp-client-grouping 113 +-- remote-address inet:host 114 +-- remote-port? inet:port-number 115 +-- local-address? inet:ip-address 116 +-- local-port? inet:port-number 117 +-- tcp-keepalives {tcp-client-keepalives}? 118 +-- idle-time? uint16 119 +-- max-probes? uint16 120 +-- probe-interval? uint16 121 grouping ip-params-grouping 122 +-- remote-address inet:host 123 +-- remote-port? inet:port-number 124 +-- local-address? inet:ip-address 125 +-- local-port? inet:port-number 126 grouping keepalives-grouping 127 +-- tcp-keepalives {tcp-client-keepalives}? 128 +-- idle-time? uint16 129 +-- max-probes? uint16 130 +-- probe-interval? uint16 132 3.2. Example Usage 134 This section presents an example showing the tcp-client-grouping 135 populated with some data. 137 138 www.example.com 139 443 140 0.0.0.0 141 0 142 143 15 144 3 145 30 146 147 149 3.3. YANG Module 151 This YANG module has normative references to [RFC6991]. 153 file "ietf-tcp-client@2019-03-09.yang" 154 module ietf-tcp-client { 155 yang-version 1.1; 156 namespace "urn:ietf:params:xml:ns:yang:ietf-tcp-client"; 157 prefix tcpc; 159 import ietf-inet-types { 160 prefix inet; 161 reference 162 "RFC 6991: Common YANG Data Types"; 163 } 165 organization 166 "IETF NETCONF (Network Configuration) Working Group"; 168 contact 169 "WG Web: 170 WG List: 171 Author: Kent Watsen "; 173 description 174 "This module defines reusable groupings for TCP clients that 175 can be used as a basis for specific TCP client instances. 177 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 178 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 179 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 180 are to be interpreted as described in BCP 14 [RFC2119] 181 [RFC8174] when, and only when, they appear in all 182 capitals, as shown here. 184 Copyright (c) 2019 IETF Trust and the persons identified as 185 authors of the code. All rights reserved. 187 Redistribution and use in source and binary forms, with or 188 without modification, is permitted pursuant to, and subject 189 to the license terms contained in, the Simplified BSD 190 License set forth in Section 4.c of the IETF Trust's 191 Legal Provisions Relating to IETF Documents 192 (http://trustee.ietf.org/license-info). 194 This version of this YANG module is part of RFC XXXX; see 195 the RFC itself for full legal notices."; 197 revision 2019-03-09 { 198 description 199 "Initial version"; 200 reference 201 "RFC XXXX: YANG Groupings for TCP Clients and TCP Servers"; 202 } 204 // Features 206 feature tcp-client-keepalives { 207 description 208 "Per socket TCP keepalive parameters are configurable for 209 TCP clients on the server implementing this feature."; 210 } 212 // Groupings 214 grouping tcp-client-grouping { 215 description 216 "A reusable grouping for configuring a TCP client."; 217 uses ip-params-grouping; 218 uses keepalives-grouping; 219 } 221 grouping ip-params-grouping { 222 description 223 "A reusable grouping for configuring TCP client IP level 224 parameters."; 225 leaf remote-address { 226 type inet:host; 227 mandatory true; 228 description 229 "The IP address or hostname of the remote peer to connect to. 230 If a domain name is configured, then the DNS resolution 231 should happen on each connection attempt. If the the DNS 232 resolution results in multiple IP addresses, the IP addresses 233 are tried according to local preference order until a 234 connection has been established or until all IP addresses 235 have failed."; 236 } 237 leaf remote-port { 238 type inet:port-number; 239 default "0"; 240 description 241 "The IP port number for the remote peer to connect to. An 242 invalid default value (0) is used (instead of 'mandatory 243 true') so that a application level data model may 'refine' 244 it with an application specific default port number value."; 245 } 246 leaf local-address { 247 type inet:ip-address; 248 description 249 "The local IP address/interface (VRF?) to bind to for when 250 connecting to the remote peer. INADDR_ANY ('0.0.0.0') or 251 INADDR6_ANY ('0:0:0:0:0:0:0:0' a.k.a. '::') MAY be used to 252 explicitly indicate the implicit default, that the server 253 can bind to any IPv4 or IPv6 addresses, respectively."; 254 } 255 leaf local-port { 256 type inet:port-number; 257 default "0"; 258 description 259 "The local IP port number to bind to for when connecting to 260 the remote peer. The port number '0', which is the default 261 value, indicates that any available local port number may 262 be used."; 263 } 264 } 266 grouping keepalives-grouping { 267 description 268 "A reusable grouping for configuring TCP client keepalive 269 parameters."; 270 container tcp-keepalives { 271 if-feature "tcp-client-keepalives"; 272 description 273 "Configures the keep-alive policy, to proactively test the 274 aliveness of the TCP server. Not all clients will use 275 all the values, based on capabilities of the underlying 276 operating system. An unresponsive TCP server is dropped 277 after approximately (idle-time * 60) + (max-probes * 278 probe-interval) seconds."; 279 leaf idle-time { 280 type uint16 { 281 range "1..max"; 282 } 283 units "minutes"; 284 description 285 "Sets the amount of time in minutes after which if no data 286 has been received from the TCP server, a TCP-level probe 287 message will be sent to test the aliveness of the TCP 288 server. When 'idle-time' is not configured (the default) 289 TCP keep-alives are disabled."; 290 } 291 leaf max-probes { 292 type uint16 { 293 range "1..max"; 294 } 295 description 296 "Sets the maximum number of sequential keep-alive probes 297 that can fail to obtain a response from the TCP server 298 before assuming the TCP server is no longer alive. If 299 no value is specified, then the operating system provided 300 default value is used."; 301 } 302 leaf probe-interval { 303 type uint16 { 304 range "1..max"; 305 } 306 units "seconds"; 307 description 308 "Sets the time interval between failed probes. If no value 309 is specified, then the operating system provided default 310 value is used."; 311 } 312 } 313 } 314 } 315 317 4. The TCP Server Model 319 4.1. Tree Diagram 321 This section provides a tree diagram [RFC8340] for the "ietf-tcp- 322 server" module. 324 module: ietf-tcp-server 326 grouping tcp-server-grouping 327 +-- local-address inet:ip-address 328 +-- local-port? inet:port-number 329 +-- tcp-keepalives {tcp-server-keepalives}? 330 +-- idle-time? uint16 331 +-- max-probes? uint16 332 +-- probe-interval? uint16 333 grouping ip-params-grouping 334 +-- local-address inet:ip-address 335 +-- local-port? inet:port-number 336 grouping keepalives-grouping 337 +-- tcp-keepalives {tcp-server-keepalives}? 338 +-- idle-time? uint16 339 +-- max-probes? uint16 340 +-- probe-interval? uint16 342 4.2. Example Usage 344 This section presents an example showing the tcp-server-grouping 345 populated with some data. 347 348 10.20.30.40 349 7777 350 351 15 352 3 353 30 354 355 357 4.3. YANG Module 359 This YANG module has normative references to [RFC6991]. 361 file "ietf-tcp-server@2019-03-09.yang" 362 module ietf-tcp-server { 363 yang-version 1.1; 364 namespace "urn:ietf:params:xml:ns:yang:ietf-tcp-server"; 365 prefix tcps; 367 import ietf-inet-types { 368 prefix inet; 369 reference 370 "RFC 6991: Common YANG Data Types"; 371 } 372 organization 373 "IETF NETCONF (Network Configuration) Working Group"; 375 contact 376 "WG Web: 377 WG List: 378 Author: Kent Watsen "; 380 description 381 "This module defines reusable groupings for TCP servers that 382 can be used as a basis for specific TCP server instances. 384 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 385 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 386 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 387 are to be interpreted as described in BCP 14 [RFC2119] 388 [RFC8174] when, and only when, they appear in all 389 capitals, as shown here. 391 Copyright (c) 2019 IETF Trust and the persons identified as 392 authors of the code. All rights reserved. 394 Redistribution and use in source and binary forms, with or 395 without modification, is permitted pursuant to, and subject 396 to the license terms contained in, the Simplified BSD 397 License set forth in Section 4.c of the IETF Trust's 398 Legal Provisions Relating to IETF Documents 399 (http://trustee.ietf.org/license-info). 401 This version of this YANG module is part of RFC XXXX; see 402 the RFC itself for full legal notices."; 404 revision 2019-03-09 { 405 description 406 "Initial version"; 407 reference 408 "RFC XXXX: YANG Groupings for TCP Clients and TCP Servers"; 409 } 411 // Features 413 feature tcp-server-keepalives { 414 description 415 "Per socket TCP keepalive parameters are configurable for 416 TCP servers on the server implementing this feature."; 417 } 419 // Groupings 420 grouping tcp-server-grouping { 421 description 422 "A reusable grouping for configuring a TCP server."; 423 uses ip-params-grouping; 424 uses keepalives-grouping; 425 } 427 grouping ip-params-grouping { 428 description 429 "A reusable grouping for configuring TCP server IP level 430 parameters."; 431 leaf local-address { 432 type inet:ip-address; 433 mandatory true; 434 description 435 "The local IP address to listen on for incoming TCL 436 client connections. INADDR_ANY (0.0.0.0) or INADDR6_ANY 437 (0:0:0:0:0:0:0:0 a.k.a. ::) MUST be used when the server 438 is to listen on all IPv4 or IPv6 addresses, respectively."; 439 } 440 leaf local-port { 441 type inet:port-number; 442 default "0"; 443 description 444 "The local port number to listen on for incoming TCP client 445 connections. An invalid default value (0) is used (instead 446 of 'mandatory true') so that a application level data model 447 may 'refine' it with an application specific default port 448 number value."; 449 } 450 } 452 grouping keepalives-grouping { 453 description 454 "A reusable grouping for configuring TCP server keepalive 455 parameters."; 456 container tcp-keepalives { 457 if-feature "tcp-server-keepalives"; 458 description 459 "Configures the keep-alive policy, to proactively test the 460 aliveness of the TCP client. Not all servers will use 461 all the values, based on capabilities of the underlying 462 operating system. An unresponsive TCP client is dropped 463 after approximately (idle-time * 60) + (max-probes * 464 probe-interval) seconds."; 465 leaf idle-time { 466 type uint16 { 467 range "1..max"; 469 } 470 units "minutes"; 471 description 472 "Sets the amount of time in minutes after which if no data 473 has been received from the TCP client, a TCP-level probe 474 message will be sent to test the aliveness of the TCP 475 client. When 'idle-time' is not configured (the default) 476 TCP keep-alives are disabled."; 477 } 478 leaf max-probes { 479 type uint16 { 480 range "1..max"; 481 } 482 description 483 "Sets the maximum number of sequential keep-alive probes 484 that can fail to obtain a response from the TCP client 485 before assuming the TCP client is no longer alive. If 486 no value is specified, then the operating system provided 487 default value is used."; 488 } 489 leaf probe-interval { 490 type uint16 { 491 range "1..max"; 492 } 493 units "seconds"; 494 description 495 "Sets the time interval between failed probes. If no value 496 is specified, then the operating system provided default 497 value is used."; 498 } 499 } 500 } 501 } 502 504 5. Security Considerations 506 The YANG modules defined in this document are designed to be accessed 507 via YANG based management protocols, such as NETCONF [RFC6241] and 508 RESTCONF [RFC8040]. Both of these protocols have mandatory-to- 509 implement secure transport layers (e.g., SSH, TCP) with mutual 510 authentication. 512 The NETCONF access control model (NACM) [RFC8341] provides the means 513 to restrict access for particular users to a pre-configured subset of 514 all available protocol operations and content. 516 Since the modules defined in this document only define groupings, 517 these considerations are primarily for the designers of other modules 518 that use these groupings. 520 There are a number of data nodes defined in the YANG modules that are 521 writable/creatable/deletable (i.e., config true, which is the 522 default). These data nodes may be considered sensitive or vulnerable 523 in some network environments. Write operations (e.g., edit-config) 524 to these data nodes without proper protection can have a negative 525 effect on network operations. These are the subtrees and data nodes 526 and their sensitivity/vulnerability: 528 NONE 530 Some of the readable data nodes in the YANG modules may be considered 531 sensitive or vulnerable in some network environments. It is thus 532 important to control read access (e.g., via get, get-config, or 533 notification) to these data nodes. These are the subtrees and data 534 nodes and their sensitivity/vulnerability: 536 NONE 538 Some of the RPC operations in this YANG module may be considered 539 sensitive or vulnerable in some network environments. It is thus 540 important to control access to these operations. These are the 541 operations and their sensitivity/vulnerability: 543 NONE 545 6. IANA Considerations 547 6.1. The IETF XML Registry 549 This document registers two URIs in the "ns" subregistry of the IETF 550 XML Registry [RFC3688]. Following the format in [RFC3688], the 551 following registrations are requested: 553 URI: urn:ietf:params:xml:ns:yang:ietf-tcp-client 554 Registrant Contact: The NETCONF WG of the IETF. 555 XML: N/A, the requested URI is an XML namespace. 557 URI: urn:ietf:params:xml:ns:yang:ietf-tcp-server 558 Registrant Contact: The NETCONF WG of the IETF. 559 XML: N/A, the requested URI is an XML namespace. 561 6.2. The YANG Module Names Registry 563 This document registers two YANG modules in the YANG Module Names 564 registry [RFC6020]. Following the format in [RFC6020], the following 565 registrations are requested: 567 name: ietf-tcp-client 568 namespace: urn:ietf:params:xml:ns:yang:ietf-tcp-client 569 prefix: tcpc 570 reference: RFC XXXX 572 name: ietf-tcp-server 573 namespace: urn:ietf:params:xml:ns:yang:ietf-tcp-server 574 prefix: tcps 575 reference: RFC XXXX 577 7. References 579 7.1. Normative References 581 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 582 Requirement Levels", BCP 14, RFC 2119, 583 DOI 10.17487/RFC2119, March 1997, 584 . 586 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 587 the Network Configuration Protocol (NETCONF)", RFC 6020, 588 DOI 10.17487/RFC6020, October 2010, 589 . 591 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 592 RFC 6991, DOI 10.17487/RFC6991, July 2013, 593 . 595 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 596 RFC 7950, DOI 10.17487/RFC7950, August 2016, 597 . 599 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 600 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 601 May 2017, . 603 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 604 Access Control Model", STD 91, RFC 8341, 605 DOI 10.17487/RFC8341, March 2018, 606 . 608 7.2. Informative References 610 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 611 DOI 10.17487/RFC3688, January 2004, 612 . 614 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 615 and A. Bierman, Ed., "Network Configuration Protocol 616 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 617 . 619 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 620 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 621 . 623 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 624 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 625 . 627 Author's Address 629 Kent Watsen 630 Watsen Networks 632 EMail: kent+ietf@watsen.net