idnits 2.17.1 draft-ietf-netconf-tcp-client-server-05.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 : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([2], [3], [4], [5], [6], [7], [8], [9], [1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 253 has weird spacing: '...nterval uin...' == Line 258 has weird spacing: '...nterval uin...' == Line 409 has weird spacing: '...address ine...' == Line 416 has weird spacing: '...nterval uin...' == Line 598 has weird spacing: '...address ine...' == (1 more instance...) -- The document date (May 20, 2020) is 1434 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) -- Looks like a reference, but probably isn't: '1' on line 873 -- Looks like a reference, but probably isn't: '2' on line 875 -- Looks like a reference, but probably isn't: '3' on line 877 -- Looks like a reference, but probably isn't: '4' on line 879 -- Looks like a reference, but probably isn't: '5' on line 881 -- Looks like a reference, but probably isn't: '6' on line 883 -- Looks like a reference, but probably isn't: '7' on line 885 -- Looks like a reference, but probably isn't: '8' on line 887 -- Looks like a reference, but probably isn't: '9' on line 890 == Missing Reference: 'RFC1122' is mentioned on line 228, but not defined == Missing Reference: 'RFC793bis' is mentioned on line 194, but not defined ** Obsolete undefined reference: RFC 793 (Obsoleted by RFC 9293) Summary: 2 errors (**), 0 flaws (~~), 9 warnings (==), 10 comments (--). 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 M. Scharf 5 Expires: November 21, 2020 Hochschule Esslingen 6 May 20, 2020 8 YANG Groupings for TCP Clients and TCP Servers 9 draft-ietf-netconf-tcp-client-server-05 11 Abstract 13 This document defines three YANG modules: the first defines a 14 grouping for configuring a generic TCP client, the second defines a 15 grouping for configuring a generic TCP server, and the third defines 16 a grouping common to the TCP clients and TCP servers. 18 Editorial Note (To be removed by RFC Editor) 20 This draft contains placeholder values that need to be replaced with 21 finalized values at the time of publication. This note summarizes 22 all of the substitutions that are needed. No other RFC Editor 23 instructions are specified elsewhere in this document. 25 Artwork in this document contains shorthand references to drafts in 26 progress. Please apply the following replacements: 28 o "DDDD" --> the assigned RFC value for this draft 30 Artwork in this document contains placeholder values for the date of 31 publication of this draft. Please apply the following replacement: 33 o "2020-05-20" --> the publication date of this draft 35 The following Appendix section is to be removed prior to publication: 37 o Appendix A. Change Log 39 Note to Reviewers (To be removed by RFC Editor) 41 This document presents a YANG module or modules that is/are part of a 42 collection of drafts that work together to produce the ultimate goal 43 of the NETCONF WG: to define configuration modules for NETCONF client 44 and servers, and RESTCONF client and servers. 46 The relationship between the various drafts in the collection is 47 presented in the below diagram. 49 crypto-types 50 ^ ^ 51 / \ 52 / \ 53 trust-anchors keystore 54 ^ ^ ^ ^ 55 | +---------+ | | 56 | | | | 57 | +------------+ | 58 tcp-client-server | / | | 59 ^ ^ ssh-client-server | | 60 | | ^ tls-client-server 61 | | | ^ ^ http-client-server 62 | | | | | ^ 63 | | | +-----+ +---------+ | 64 | | | | | | 65 | +-----------|--------|--------------+ | | 66 | | | | | | 67 +-----------+ | | | | | 68 | | | | | | 69 | | | | | | 70 netconf-client-server restconf-client-server 72 Full draft names and link to drafts: 74 o draft-ietf-netconf-crypto-types (html [1]) 76 o draft-ietf-netconf-trust-anchors (html [2]) 78 o draft-ietf-netconf-keystore (html [3]) 80 o draft-ietf-netconf-tcp-client-server (html [4]) 82 o draft-ietf-netconf-ssh-client-server (html [5]) 84 o draft-ietf-netconf-tls-client-server (html [6]) 86 o draft-ietf-netconf-http-client-server (html [7]) 88 o draft-ietf-netconf-netconf-client-server (html [8]) 90 o draft-ietf-netconf-restconf-client-server (html [9]) 92 Status of This Memo 94 This Internet-Draft is submitted in full conformance with the 95 provisions of BCP 78 and BCP 79. 97 Internet-Drafts are working documents of the Internet Engineering 98 Task Force (IETF). Note that other groups may also distribute 99 working documents as Internet-Drafts. The list of current Internet- 100 Drafts is at https://datatracker.ietf.org/drafts/current/. 102 Internet-Drafts are draft documents valid for a maximum of six months 103 and may be updated, replaced, or obsoleted by other documents at any 104 time. It is inappropriate to use Internet-Drafts as reference 105 material or to cite them other than as "work in progress." 107 This Internet-Draft will expire on November 21, 2020. 109 Copyright Notice 111 Copyright (c) 2020 IETF Trust and the persons identified as the 112 document authors. All rights reserved. 114 This document is subject to BCP 78 and the IETF Trust's Legal 115 Provisions Relating to IETF Documents 116 (https://trustee.ietf.org/license-info) in effect on the date of 117 publication of this document. Please review these documents 118 carefully, as they describe your rights and restrictions with respect 119 to this document. Code Components extracted from this document must 120 include Simplified BSD License text as described in Section 4.e of 121 the Trust Legal Provisions and are provided without warranty as 122 described in the Simplified BSD License. 124 Table of Contents 126 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 127 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 128 3. The TCP Common Model . . . . . . . . . . . . . . . . . . . . 4 129 3.1. Model Scope . . . . . . . . . . . . . . . . . . . . . . . 4 130 3.2. Usage Guidelines for Configuring TCP Keep-Alives . . . . 5 131 3.3. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 6 132 3.4. Example Usage . . . . . . . . . . . . . . . . . . . . . . 6 133 3.5. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 6 134 4. The TCP Client Model . . . . . . . . . . . . . . . . . . . . 9 135 4.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 9 136 4.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 9 137 4.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 10 138 5. The TCP Server Model . . . . . . . . . . . . . . . . . . . . 13 139 5.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 13 140 5.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 13 141 5.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 14 142 6. Security Considerations . . . . . . . . . . . . . . . . . . . 16 143 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 144 7.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 17 145 7.2. The YANG Module Names Registry . . . . . . . . . . . . . 18 146 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 18 147 8.1. Normative References . . . . . . . . . . . . . . . . . . 18 148 8.2. Informative References . . . . . . . . . . . . . . . . . 19 149 8.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 19 150 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 20 151 A.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 20 152 A.2. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 20 153 A.3. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 20 154 A.4. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 20 155 A.5. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 20 156 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 20 158 1. Introduction 160 This document defines three YANG 1.1 [RFC7950] modules: the first 161 defines a grouping for configuring a generic TCP client, the second 162 defines a grouping for configuring a generic TCP server, and the 163 third defines a grouping common to the TCP clients and TCP servers. 165 It is intended that these groupings will be used either standalone, 166 for TCP-based protocols, as part of a stack of protocol-specific 167 configuration models. For instance, these groupings could help 168 define the configuration module for SSH, TLS, or HTTP based 169 applications. 171 2. Terminology 173 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 174 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 175 "OPTIONAL" in this document are to be interpreted as described in BCP 176 14 [RFC2119] [RFC8174] when, and only when, they appear in all 177 capitals, as shown here. 179 3. The TCP Common Model 181 3.1. Model Scope 183 This document defines a common "grouping" statement for basic TCP 184 connection parameters that matter to applications. In some TCP 185 stacks, such parameters can also directly be set by an application 186 using system calls, such as the socket API. The base YANG model in 187 this document focuses on modeling TCP keep-alives. This base model 188 can be extended as needed. 190 3.2. Usage Guidelines for Configuring TCP Keep-Alives 192 Network stacks may include "keep-alives" in their TCP 193 implementations, although this practice is not universally accepted. 194 If keep-alives are included, [RFC1122] [RFC793bis] mandates that the 195 application MUST be able to turn them on or off for each TCP 196 connection, and that they MUST default to off. 198 Keep-alive mechanisms exist in many protocols. Depending on the 199 protocol stack, TCP keep-alives may only be one out of several 200 alternatives. Which mechanism(s) to use depends on the use case and 201 application requirements. If keep-alives are needed by an 202 application, it is RECOMMENDED that the aliveness check happens only 203 at the protocol layers that are meaningful to the application. 205 A TCP keep-alive mechanism SHOULD only be invoked in server 206 applications that might otherwise hang indefinitely and consume 207 resources unnecessarily if a client crashes or aborts a connection 208 during a network failure [RFC1122]. TCP keep-alives may consume 209 significant resources both in the network and in endpoints (e.g., 210 battery power). In addition, frequent keep-alives risk network 211 congestion. The higher the frequency of keep-alives, the higher the 212 overhead. 214 Given the cost of keep-alives, parameters have to be configured 215 carefully: 217 o The default idle interval (leaf "idle-time") MUST default to no 218 less than two hours, i.e., 7200 seconds [RFC1122]. A lower value 219 MAY be configured, but keep-alive messages SHOULD NOT be 220 transmitted more frequently than once every 15 seconds. Longer 221 intervals SHOULD be used when possible. 223 o The maximum number of sequential keep-alive probes that can fail 224 (leaf "max-probes") trades off responsiveness and robustness 225 against packet loss. ACK segments that contain no data are not 226 reliably transmitted by TCP. Consequently, if a keep-alive 227 mechanism is implemented it MUST NOT interpret failure to respond 228 to any specific probe as a dead connection [RFC1122]. Typically a 229 single-digit number should suffice. 231 o TCP implementations may include a parameter for the number of 232 seconds between TCP keep-alive probes (leaf "probe-interval"). In 233 order to avoid congestion, the time interval between probes MUST 234 NOT be smaller than one second. Significantly longer intervals 235 SHOULD be used. It is important to note that keep-alive probes 236 (or replies) can get dropped due to network congestion. Sending 237 further probe messages into a congested path after a short 238 interval, without backing off timers, could cause harm and result 239 in a congestion collapse. Therefore it is essential to pick a 240 large, conservative value for this interval. 242 3.3. Tree Diagram 244 This section provides a tree diagram [RFC8340] for the "ietf-tcp- 245 common" module. 247 module: ietf-tcp-common 249 grouping tcp-common-grouping 250 +-- keepalives! {keepalives-supported}? 251 +-- idle-time uint16 252 +-- max-probes uint16 253 +-- probe-interval uint16 254 grouping tcp-connection-grouping 255 +-- keepalives! {keepalives-supported}? 256 +-- idle-time uint16 257 +-- max-probes uint16 258 +-- probe-interval uint16 260 3.4. Example Usage 262 This section presents an example showing the "tcp-common-grouping" 263 populated with some data. 265 266 267 15 268 3 269 30 270 271 273 3.5. YANG Module 275 The ietf-tcp-common YANG module references [RFC6991]. 277 file "ietf-tcp-common@2020-05-20.yang" 279 module ietf-tcp-common { 280 yang-version 1.1; 281 namespace "urn:ietf:params:xml:ns:yang:ietf-tcp-common"; 282 prefix tcpcmn; 283 organization 284 "IETF NETCONF (Network Configuration) Working Group and the 285 IETF TCP Maintenance and Minor Extensions (TCPM) Working Group"; 287 contact 288 "WG Web: 289 290 WG List: 291 292 Authors: Kent Watsen 293 Michael Scharf 294 "; 296 description 297 "This module defines reusable groupings for TCP commons that 298 can be used as a basis for specific TCP common instances. 300 Copyright (c) 2020 IETF Trust and the persons identified 301 as authors of the code. All rights reserved. 303 Redistribution and use in source and binary forms, with 304 or without modification, is permitted pursuant to, and 305 subject to the license terms contained in, the Simplified 306 BSD License set forth in Section 4.c of the IETF Trust's 307 Legal Provisions Relating to IETF Documents 308 (https://trustee.ietf.org/license-info). 310 This version of this YANG module is part of RFC DDDD 311 (https://www.rfc-editor.org/info/rfcDDDD); see the RFC 312 itself for full legal notices. 314 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 315 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 316 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 317 are to be interpreted as described in BCP 14 (RFC 2119) 318 (RFC 8174) when, and only when, they appear in all 319 capitals, as shown here."; 321 revision 2020-05-20 { 322 description 323 "Initial version"; 324 reference 325 "RFC DDDD: YANG Groupings for TCP Clients and TCP Servers"; 326 } 328 // Features 329 feature keepalives-supported { 330 description 331 "Indicates that keepalives are supported."; 332 } 334 // Groupings 336 grouping tcp-common-grouping { 337 description 338 "A reusable grouping for configuring TCP parameters common 339 to TCP connections as well as the operating system as a 340 whole."; 341 container keepalives { 342 if-feature "keepalives-supported"; 343 presence "Indicates that keepalives are enabled."; 344 description 345 "Configures the keep-alive policy, to proactively test the 346 aliveness of the TCP peer. An unresponsive TCP peer is 347 dropped after approximately (idle-time + max-probes 348 * probe-interval) seconds."; 349 leaf idle-time { 350 type uint16 { 351 range "1..max"; 352 } 353 units "seconds"; 354 mandatory true; 355 description 356 "Sets the amount of time after which if no data has been 357 received from the TCP peer, a TCP-level probe message 358 will be sent to test the aliveness of the TCP peer. 359 Two hours (7200 seconds) is safe value, per RFC 1122."; 360 reference 361 "RFC 1122: 362 Requirements for Internet Hosts -- Communication Layers"; 363 } 364 leaf max-probes { 365 type uint16 { 366 range "1..max"; 367 } 368 mandatory true; 369 description 370 "Sets the maximum number of sequential keep-alive probes 371 that can fail to obtain a response from the TCP peer 372 before assuming the TCP peer is no longer alive."; 373 } 374 leaf probe-interval { 375 type uint16 { 376 range "1..max"; 377 } 378 units "seconds"; 379 mandatory true; 380 description 381 "Sets the time interval between failed probes. The interval 382 SHOULD be significantly longer than one second in order to 383 avoid harm on a congested link."; 384 } 385 } // container keepalives 386 } // grouping tcp-common-grouping 388 grouping tcp-connection-grouping { 389 description 390 "A reusable grouping for configuring TCP parameters common 391 to TCP connections."; 392 uses tcp-common-grouping; 393 } 395 } 397 399 4. The TCP Client Model 401 4.1. Tree Diagram 403 This section provides a tree diagram [RFC8340] for the "ietf-tcp- 404 client" module. 406 module: ietf-tcp-client 408 grouping tcp-client-grouping 409 +-- remote-address inet:host 410 +-- remote-port? inet:port-number 411 +-- local-address? inet:ip-address {local-binding-supported}? 412 +-- local-port? inet:port-number {local-binding-supported}? 413 +-- keepalives! {keepalives-supported}? 414 +-- idle-time uint16 415 +-- max-probes uint16 416 +-- probe-interval uint16 418 4.2. Example Usage 420 This section presents an example showing the "tcp-client-grouping" 421 populated with some data. 423 424 www.example.com 425 443 426 0.0.0.0 427 0 428 429 15 430 3 431 30 432 433 435 4.3. YANG Module 437 The ietf-tcp-client YANG module references [RFC6991]. 439 file "ietf-tcp-client@2020-05-20.yang" 441 module ietf-tcp-client { 442 yang-version 1.1; 443 namespace "urn:ietf:params:xml:ns:yang:ietf-tcp-client"; 444 prefix tcpc; 446 import ietf-inet-types { 447 prefix inet; 448 reference 449 "RFC 6991: Common YANG Data Types"; 450 } 452 import ietf-tcp-common { 453 prefix tcpcmn; 454 reference 455 "RFC DDDD: YANG Groupings for TCP Clients and TCP Servers"; 456 } 458 organization 459 "IETF NETCONF (Network Configuration) Working Group and the 460 IETF TCP Maintenance and Minor Extensions (TCPM) Working Group"; 462 contact 463 "WG Web: 464 465 WG List: 466 467 Authors: Kent Watsen 468 Michael Scharf 469 "; 471 description 472 "This module defines reusable groupings for TCP clients that 473 can be used as a basis for specific TCP client instances. 475 Copyright (c) 2020 IETF Trust and the persons identified 476 as authors of the code. All rights reserved. 478 Redistribution and use in source and binary forms, with 479 or without modification, is permitted pursuant to, and 480 subject to the license terms contained in, the Simplified 481 BSD License set forth in Section 4.c of the IETF Trust's 482 Legal Provisions Relating to IETF Documents 483 (https://trustee.ietf.org/license-info). 485 This version of this YANG module is part of RFC DDDD 486 (https://www.rfc-editor.org/info/rfcDDDD); see the RFC 487 itself for full legal notices. 489 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 490 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 491 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 492 are to be interpreted as described in BCP 14 (RFC 2119) 493 (RFC 8174) when, and only when, they appear in all 494 capitals, as shown here."; 496 revision 2020-05-20 { 497 description 498 "Initial version"; 499 reference 500 "RFC DDDD: YANG Groupings for TCP Clients and TCP Servers"; 501 } 503 // Features 505 feature local-binding-supported { 506 description 507 "Indicates that the server supports configuring local 508 bindings (i.e., the local address and local port) for 509 TCP clients."; 510 } 512 feature tcp-client-keepalives { 513 description 514 "Per socket TCP keepalive parameters are configurable for 515 TCP clients on the server implementing this feature."; 516 } 518 // Groupings 519 grouping tcp-client-grouping { 520 description 521 "A reusable grouping for configuring a TCP client. 523 Note that this grouping uses fairly typical descendent 524 node names such that a stack of 'uses' statements will 525 have name conflicts. It is intended that the consuming 526 data model will resolve the issue (e.g., by wrapping 527 the 'uses' statement in a container called 528 'tcp-client-parameters'). This model purposely does 529 not do this itself so as to provide maximum flexibility 530 to consuming models."; 532 leaf remote-address { 533 type inet:host; 534 mandatory true; 535 description 536 "The IP address or hostname of the remote peer to 537 establish a connection with. If a domain name is 538 configured, then the DNS resolution should happen on 539 each connection attempt. If the DNS resolution 540 results in multiple IP addresses, the IP addresses 541 are tried according to local preference order until 542 a connection has been established or until all IP 543 addresses have failed."; 544 } 545 leaf remote-port { 546 type inet:port-number; 547 default "0"; 548 description 549 "The IP port number for the remote peer to establish a 550 connection with. An invalid default value (0) is used 551 (instead of 'mandatory true') so that as application 552 level data model may 'refine' it with an application 553 specific default port number value."; 554 } 555 leaf local-address { 556 if-feature "local-binding-supported"; 557 type inet:ip-address; 558 description 559 "The local IP address/interface (VRF?) to bind to for when 560 connecting to the remote peer. INADDR_ANY ('0.0.0.0') or 561 INADDR6_ANY ('0:0:0:0:0:0:0:0' a.k.a. '::') MAY be used to 562 explicitly indicate the implicit default, that the server 563 can bind to any IPv4 or IPv6 addresses, respectively."; 564 } 565 leaf local-port { 566 if-feature "local-binding-supported"; 567 type inet:port-number; 568 default "0"; 569 description 570 "The local IP port number to bind to for when connecting 571 to the remote peer. The port number '0', which is the 572 default value, indicates that any available local port 573 number may be used."; 574 } 575 uses tcpcmn:tcp-connection-grouping { 576 augment "keepalives" { 577 if-feature "tcp-client-keepalives"; 578 description 579 "Add an if-feature statement so that implementations 580 can choose to support TCP client keepalives."; 581 } 582 } 583 } 584 } 586 588 5. The TCP Server Model 590 5.1. Tree Diagram 592 This section provides a tree diagram [RFC8340] for the "ietf-tcp- 593 server" module. 595 module: ietf-tcp-server 597 grouping tcp-server-grouping 598 +-- local-address inet:ip-address 599 +-- local-port? inet:port-number 600 +-- keepalives! {keepalives-supported}? 601 +-- idle-time uint16 602 +-- max-probes uint16 603 +-- probe-interval uint16 605 5.2. Example Usage 607 This section presents an example showing the "tcp-server-grouping" 608 populated with some data. 610 611 10.20.30.40 612 7777 613 614 15 615 3 616 30 617 618 620 5.3. YANG Module 622 The ietf-tcp-server YANG module references [RFC6991]. 624 file "ietf-tcp-server@2020-05-20.yang" 626 module ietf-tcp-server { 627 yang-version 1.1; 628 namespace "urn:ietf:params:xml:ns:yang:ietf-tcp-server"; 629 prefix tcps; 631 import ietf-inet-types { 632 prefix inet; 633 reference 634 "RFC 6991: Common YANG Data Types"; 635 } 637 import ietf-tcp-common { 638 prefix tcpcmn; 639 reference 640 "RFC DDDD: YANG Groupings for TCP Clients and TCP Servers"; 641 } 643 organization 644 "IETF NETCONF (Network Configuration) Working Group and the 645 IETF TCP Maintenance and Minor Extensions (TCPM) Working Group"; 647 contact 648 "WG Web: 649 650 WG List: 651 652 Authors: Kent Watsen 653 Michael Scharf 654 "; 656 description 657 "This module defines reusable groupings for TCP servers that 658 can be used as a basis for specific TCP server instances. 660 Copyright (c) 2020 IETF Trust and the persons identified 661 as authors of the code. All rights reserved. 663 Redistribution and use in source and binary forms, with 664 or without modification, is permitted pursuant to, and 665 subject to the license terms contained in, the Simplified 666 BSD License set forth in Section 4.c of the IETF Trust's 667 Legal Provisions Relating to IETF Documents 668 (https://trustee.ietf.org/license-info). 670 This version of this YANG module is part of RFC DDDD 671 (https://www.rfc-editor.org/info/rfcDDDD); see the RFC 672 itself for full legal notices. 674 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 675 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 676 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 677 are to be interpreted as described in BCP 14 (RFC 2119) 678 (RFC 8174) when, and only when, they appear in all 679 capitals, as shown here."; 681 revision 2020-05-20 { 682 description 683 "Initial version"; 684 reference 685 "RFC DDDD: YANG Groupings for TCP Clients and TCP Servers"; 686 } 688 // Features 690 feature tcp-server-keepalives { 691 description 692 "Per socket TCP keepalive parameters are configurable for 693 TCP servers on the server implementing this feature."; 694 } 696 // Groupings 698 grouping tcp-server-grouping { 699 description 700 "A reusable grouping for configuring a TCP server. 702 Note that this grouping uses fairly typical descendent 703 node names such that a stack of 'uses' statements will 704 have name conflicts. It is intended that the consuming 705 data model will resolve the issue (e.g., by wrapping 706 the 'uses' statement in a container called 707 'tcp-server-parameters'). This model purposely does 708 not do this itself so as to provide maximum flexibility 709 to consuming models."; 710 leaf local-address { 711 type inet:ip-address; 712 mandatory true; 713 description 714 "The local IP address to listen on for incoming 715 TCP client connections. INADDR_ANY (0.0.0.0) or 716 INADDR6_ANY (0:0:0:0:0:0:0:0 a.k.a. ::) MUST be 717 used when the server is to listen on all IPv4 or 718 IPv6 addresses, respectively."; 719 } 720 leaf local-port { 721 type inet:port-number; 722 default "0"; 723 description 724 "The local port number to listen on for incoming TCP 725 client connections. An invalid default value (0) 726 is used (instead of 'mandatory true') so that an 727 application level data model may 'refine' it with 728 an application specific default port number value."; 729 } 730 uses tcpcmn:tcp-connection-grouping { 731 augment "keepalives" { 732 if-feature "tcp-server-keepalives"; 733 description 734 "Add an if-feature statement so that implementations 735 can choose to support TCP server keepalives."; 736 } 737 } 738 } 739 } 741 743 6. Security Considerations 745 The YANG modules defined in this document are designed to be accessed 746 via YANG based management protocols, such as NETCONF [RFC6241] and 747 RESTCONF [RFC8040]. Both of these protocols have mandatory-to- 748 implement secure transport layers (e.g., SSH, TCP) with mutual 749 authentication. 751 The NETCONF access control model (NACM) [RFC8341] provides the means 752 to restrict access for particular users to a pre-configured subset of 753 all available protocol operations and content. 755 Since the modules defined in this document only define groupings, 756 these considerations are primarily for the designers of other modules 757 that use these groupings. 759 There are a number of data nodes defined in the YANG modules that are 760 writable/creatable/deletable (i.e., config true, which is the 761 default). These data nodes may be considered sensitive or vulnerable 762 in some network environments. Write operations (e.g., edit-config) 763 to these data nodes without proper protection can have a negative 764 effect on network operations. These are the subtrees and data nodes 765 and their sensitivity/vulnerability: 767 None of the writable/creatable/deletable data nodes in 768 the YANG modules defined in this document are considered more 769 sensitive or vulnerable then standard configuration. 771 Some of the readable data nodes in the YANG modules may be considered 772 sensitive or vulnerable in some network environments. It is thus 773 important to control read access (e.g., via get, get-config, or 774 notification) to these data nodes. These are the subtrees and data 775 nodes and their sensitivity/vulnerability: 777 None of the readable data nodes in the YANG modules 778 defined in this document are considered more sensitive or vulnerable 779 then standard configuration. 781 This document does not define any RPC actions and hence this section 782 does not consider the security of RPCs. 784 7. IANA Considerations 786 7.1. The IETF XML Registry 788 This document registers two URIs in the "ns" subregistry of the IETF 789 XML Registry [RFC3688]. Following the format in [RFC3688], the 790 following registrations are requested: 792 URI: urn:ietf:params:xml:ns:yang:ietf-tcp-client 793 Registrant Contact: The NETCONF WG of the IETF. 794 XML: N/A, the requested URI is an XML namespace. 796 URI: urn:ietf:params:xml:ns:yang:ietf-tcp-server 797 Registrant Contact: The NETCONF WG of the IETF. 798 XML: N/A, the requested URI is an XML namespace. 800 7.2. The YANG Module Names Registry 802 This document registers two YANG modules in the YANG Module Names 803 registry [RFC6020]. Following the format in [RFC6020], the following 804 registrations are requested: 806 name: ietf-tcp-common 807 namespace: urn:ietf:params:xml:ns:yang:ietf-tcp-common 808 prefix: tcpcmn 809 reference: RFC DDDD 811 name: ietf-tcp-client 812 namespace: urn:ietf:params:xml:ns:yang:ietf-tcp-client 813 prefix: tcpc 814 reference: RFC DDDD 816 name: ietf-tcp-server 817 namespace: urn:ietf:params:xml:ns:yang:ietf-tcp-server 818 prefix: tcps 819 reference: RFC DDDD 821 8. References 823 8.1. Normative References 825 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 826 Requirement Levels", BCP 14, RFC 2119, 827 DOI 10.17487/RFC2119, March 1997, 828 . 830 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 831 the Network Configuration Protocol (NETCONF)", RFC 6020, 832 DOI 10.17487/RFC6020, October 2010, 833 . 835 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 836 RFC 6991, DOI 10.17487/RFC6991, July 2013, 837 . 839 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 840 RFC 7950, DOI 10.17487/RFC7950, August 2016, 841 . 843 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 844 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 845 May 2017, . 847 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 848 Access Control Model", STD 91, RFC 8341, 849 DOI 10.17487/RFC8341, March 2018, 850 . 852 8.2. Informative References 854 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 855 DOI 10.17487/RFC3688, January 2004, 856 . 858 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 859 and A. Bierman, Ed., "Network Configuration Protocol 860 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 861 . 863 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 864 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 865 . 867 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 868 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 869 . 871 8.3. URIs 873 [1] https://tools.ietf.org/html/draft-ietf-netconf-crypto-types 875 [2] https://tools.ietf.org/html/draft-ietf-netconf-trust-anchors 877 [3] https://tools.ietf.org/html/draft-ietf-netconf-keystore 879 [4] https://tools.ietf.org/html/draft-ietf-netconf-tcp-client-server 881 [5] https://tools.ietf.org/html/draft-ietf-netconf-ssh-client-server 883 [6] https://tools.ietf.org/html/draft-ietf-netconf-tls-client-server 885 [7] https://tools.ietf.org/html/draft-ietf-netconf-http-client-server 887 [8] https://tools.ietf.org/html/draft-ietf-netconf-netconf-client- 888 server 890 [9] https://tools.ietf.org/html/draft-ietf-netconf-restconf-client- 891 server 893 Appendix A. Change Log 895 A.1. 00 to 01 897 o Added 'local-binding-supported' feature to TCP-client model. 899 o Added 'keepalives-supported' feature to TCP-common model. 901 o Added 'external-endpoint-values' container and 'external- 902 endpoints' feature to TCP-server model. 904 A.2. 01 to 02 906 o Removed the 'external-endpoint-values' container and 'external- 907 endpoints' feature from the TCP-server model. 909 A.3. 02 to 03 911 o Moved the common model section to be before the client and server 912 specific sections. 914 o Added sections "Model Scope" and "Usage Guidelines for Configuring 915 TCP Keep-Alives" to the common model section. 917 A.4. 03 to 04 919 o Fixed a few typos. 921 A.5. 04 to 05 923 o Removed commented out "grouping tcp-system-grouping" statement 924 kept for reviewers. 926 o Added a "Note to Reviewers" note to first page. 928 Authors' Addresses 930 Kent Watsen 931 Watsen Networks 933 EMail: kent+ietf@watsen.net 935 Michael Scharf 936 Hochschule Esslingen - University of Applied Sciences 938 EMail: michael.scharf@hs-esslingen.de