idnits 2.17.1 draft-ietf-netconf-tcp-client-server-07.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 ([RFC7950]), 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 232 has weird spacing: '...nterval uin...' == Line 401 has weird spacing: '...is node must ...' == Line 499 has weird spacing: '...address ine...' == Line 503 has weird spacing: '...address ine...' -- The document date (8 July 2020) is 1381 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) == Missing Reference: 'RFC1122' is mentioned on line 300, but not defined == Missing Reference: 'RFC793bis' is mentioned on line 266, but not defined ** Obsolete undefined reference: RFC 793 (Obsoleted by RFC 9293) == Outdated reference: A later version (-34) exists of draft-ietf-netconf-crypto-types-15 == Outdated reference: A later version (-20) exists of draft-ietf-netconf-http-client-server-03 == Outdated reference: A later version (-35) exists of draft-ietf-netconf-keystore-17 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-netconf-client-server-19 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-restconf-client-server-19 == Outdated reference: A later version (-40) exists of draft-ietf-netconf-ssh-client-server-19 == Outdated reference: A later version (-26) exists of draft-ietf-netconf-tcp-client-server-06 == Outdated reference: A later version (-41) exists of draft-ietf-netconf-tls-client-server-19 == Outdated reference: A later version (-28) exists of draft-ietf-netconf-trust-anchors-10 Summary: 2 errors (**), 0 flaws (~~), 16 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 M. Scharf 5 Expires: 9 January 2021 Hochschule Esslingen 6 8 July 2020 8 YANG Groupings for TCP Clients and TCP Servers 9 draft-ietf-netconf-tcp-client-server-07 11 Abstract 13 This document defines three YANG 1.1 [RFC7950] modules to support the 14 configuration of TCP clients and TCP servers, either as standalone or 15 in conjunction with a stack protocol layer specific configurations. 17 Editorial Note (To be removed by RFC Editor) 19 This draft contains placeholder values that need to be replaced with 20 finalized values at the time of publication. This note summarizes 21 all of the substitutions that are needed. No other RFC Editor 22 instructions are specified elsewhere in this document. 24 Artwork in this document contains shorthand references to drafts in 25 progress. Please apply the following replacements: 27 * "DDDD" --> the assigned RFC value for this draft 29 Artwork in this document contains placeholder values for the date of 30 publication of this draft. Please apply the following replacement: 32 * "2020-07-08" --> the publication date of this draft 34 The following Appendix section is to be removed prior to publication: 36 * Appendix A. Change Log 38 Status of This Memo 40 This Internet-Draft is submitted in full conformance with the 41 provisions of BCP 78 and BCP 79. 43 Internet-Drafts are working documents of the Internet Engineering 44 Task Force (IETF). Note that other groups may also distribute 45 working documents as Internet-Drafts. The list of current Internet- 46 Drafts is at https://datatracker.ietf.org/drafts/current/. 48 Internet-Drafts are draft documents valid for a maximum of six months 49 and may be updated, replaced, or obsoleted by other documents at any 50 time. It is inappropriate to use Internet-Drafts as reference 51 material or to cite them other than as "work in progress." 53 This Internet-Draft will expire on 9 January 2021. 55 Copyright Notice 57 Copyright (c) 2020 IETF Trust and the persons identified as the 58 document authors. All rights reserved. 60 This document is subject to BCP 78 and the IETF Trust's Legal 61 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 62 license-info) in effect on the date of publication of this document. 63 Please review these documents carefully, as they describe your rights 64 and restrictions with respect to this document. Code Components 65 extracted from this document must include Simplified BSD License text 66 as described in Section 4.e of the Trust Legal Provisions and are 67 provided without warranty as described in the Simplified BSD License. 69 Table of Contents 71 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 72 1.1. Relation to other RFCs . . . . . . . . . . . . . . . . . 3 73 1.2. Specification Language . . . . . . . . . . . . . . . . . 5 74 1.3. Adherence to the NMDA . . . . . . . . . . . . . . . . . . 5 75 2. The "ietf-tcp-common" Module . . . . . . . . . . . . . . . . 5 76 2.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 5 77 2.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 7 78 2.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 8 79 3. The "ietf-tcp-client" Module . . . . . . . . . . . . . . . . 11 80 3.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 11 81 3.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 13 82 3.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 13 83 4. The "ietf-tcp-server" Module . . . . . . . . . . . . . . . . 20 84 4.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 20 85 4.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 21 86 4.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 21 87 5. Security Considerations . . . . . . . . . . . . . . . . . . . 24 88 5.1. The "ietf-tcp-common" YANG Module . . . . . . . . . . . . 24 89 5.2. The "ietf-tcp-client" YANG Module . . . . . . . . . . . . 25 90 5.3. The "ietf-tcp-server" YANG Module . . . . . . . . . . . . 26 91 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26 92 6.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 26 93 6.2. The YANG Module Names Registry . . . . . . . . . . . . . 27 94 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 27 95 7.1. Normative References . . . . . . . . . . . . . . . . . . 27 96 7.2. Informative References . . . . . . . . . . . . . . . . . 28 97 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 29 98 A.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 29 99 A.2. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 30 100 A.3. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 30 101 A.4. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 30 102 A.5. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 30 103 A.6. 05 to 06 . . . . . . . . . . . . . . . . . . . . . . . . 30 104 A.7. 06 to 07 . . . . . . . . . . . . . . . . . . . . . . . . 30 105 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 30 107 1. Introduction 109 This document defines three YANG 1.1 [RFC7950] modules to support the 110 configuration of TCP clients and TCP servers, either as standalone or 111 in conjunction with a stack protocol layer specific configurations. 113 1.1. Relation to other RFCs 115 This document presents one or more YANG modules [RFC7950] that are 116 part of a collection of RFCs that work together to define 117 configuration modules for clients and servers of both the NETCONF 118 [RFC6241] and RESTCONF [RFC8040] protocols. 120 The modules have been defined in a modular fashion to enable their 121 use by other efforts, some of which are known to be in progress at 122 the time of this writing, with many more expected to be defined in 123 time. 125 The relationship between the various RFCs in the collection is 126 presented in the below diagram. The labels in the diagram represent 127 the primary purpose provided by each RFC. Links the each RFC are 128 provided below the diagram. 130 crypto-types 131 ^ ^ 132 / \ 133 / \ 134 truststore keystore 135 ^ ^ ^ ^ 136 | +---------+ | | 137 | | | | 138 | +------------+ | 139 tcp-client-server | / | | 140 ^ ^ ssh-client-server | | 141 | | ^ tls-client-server 142 | | | ^ ^ http-client-server 143 | | | | | ^ 144 | | | +-----+ +---------+ | 145 | | | | | | 146 | +-----------|--------|--------------+ | | 147 | | | | | | 148 +-----------+ | | | | | 149 | | | | | | 150 | | | | | | 151 netconf-client-server restconf-client-server 153 +=======================+===========================================+ 154 | Label in Diagram | Originating RFC | 155 +=======================+===========================================+ 156 | crypto-types | [I-D.ietf-netconf-crypto-types] | 157 +-----------------------+-------------------------------------------+ 158 | truststore | [I-D.ietf-netconf-trust-anchors] | 159 +-----------------------+-------------------------------------------+ 160 | keystore | [I-D.ietf-netconf-keystore] | 161 +-----------------------+-------------------------------------------+ 162 | tcp-client-server | [I-D.ietf-netconf-tcp-client-server] | 163 +-----------------------+-------------------------------------------+ 164 | ssh-client-server | [I-D.ietf-netconf-ssh-client-server] | 165 +-----------------------+-------------------------------------------+ 166 | tls-client-server | [I-D.ietf-netconf-tls-client-server] | 167 +-----------------------+-------------------------------------------+ 168 | http-client-server | [I-D.ietf-netconf-http-client-server] | 169 +-----------------------+-------------------------------------------+ 170 | netconf-client-server | [I-D.ietf-netconf-netconf-client-server] | 171 +-----------------------+-------------------------------------------+ 172 |restconf-client-server | [I-D.ietf-netconf-restconf-client-server] | 173 +-----------------------+-------------------------------------------+ 175 Table 1: Label to RFC Mapping 177 1.2. Specification Language 179 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 180 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 181 "OPTIONAL" in this document are to be interpreted as described in BCP 182 14 [RFC2119] [RFC8174] when, and only when, they appear in all 183 capitals, as shown here. 185 1.3. Adherence to the NMDA 187 This document in compliant with the Network Management Datastore 188 Architecture (NMDA) [RFC8342]. It does not define any protocol 189 accessible nodes that are "config false". 191 2. The "ietf-tcp-common" Module 193 2.1. Data Model Overview 195 2.1.1. Model Scope 197 This document defines a common "grouping" statement for basic TCP 198 connection parameters that matter to applications. In some TCP 199 stacks, such parameters can also directly be set by an application 200 using system calls, such as the socket API. The base YANG model in 201 this document focuses on modeling TCP keep-alives. This base model 202 can be extended as needed. 204 2.1.2. Features 206 The following diagram lists all the "feature" statements defined in 207 the "ietf-tcp-common" module: 209 Features: 210 +-- keepalives-supported 212 2.1.3. Groupings 214 The following diagram lists all the "grouping" statements defined in 215 the "ietf-keystore" module: 217 Groupings: 218 +-- tcp-common-grouping 219 +-- tcp-connection-grouping 221 Each of these groupings are presented in the following subsections. 223 2.1.3.1. The "tcp-common-grouping" Grouping 225 The following tree diagram [RFC8340] illustrates the "tcp-common- 226 grouping" grouping: 228 grouping tcp-common-grouping 229 +-- keepalives! {keepalives-supported}? 230 +-- idle-time uint16 231 +-- max-probes uint16 232 +-- probe-interval uint16 234 Comments: 236 * The "keepalives" node is a "presence" node so that the decendent 237 nodes' "mandatory true" doesn't imply that keepalives must be 238 configured. 240 * The "idle-time", "max-probes", and "probe-interval" nodes have the 241 common meanings. Please see the YANG module in Section 2.3 for 242 details. 244 2.1.3.2. The "tcp-connection-grouping" Grouping 246 The following tree diagram [RFC8340] illustrates the "tcp-connection- 247 grouping" grouping: 249 grouping tcp-connection-grouping 250 +---u tcp-common-grouping 252 Comments: 254 * This grouping uses the "tcp-common-grouping" grouping discussed in 255 Section 2.1.3.1. 257 2.1.4. Protocol-accessible Nodes 259 The "ietf-tcp-common" module does not contain any protocol-accessible 260 nodes. 262 2.1.5. Guidelines for Configuring TCP Keep-Alives 264 Network stacks may include "keep-alives" in their TCP 265 implementations, although this practice is not universally accepted. 266 If keep-alives are included, [RFC1122] [RFC793bis] mandates that the 267 application MUST be able to turn them on or off for each TCP 268 connection, and that they MUST default to off. 270 Keep-alive mechanisms exist in many protocols. Depending on the 271 protocol stack, TCP keep-alives may only be one out of several 272 alternatives. Which mechanism(s) to use depends on the use case and 273 application requirements. If keep-alives are needed by an 274 application, it is RECOMMENDED that the aliveness check happens only 275 at the protocol layers that are meaningful to the application. 277 A TCP keep-alive mechanism SHOULD only be invoked in server 278 applications that might otherwise hang indefinitely and consume 279 resources unnecessarily if a client crashes or aborts a connection 280 during a network failure [RFC1122]. TCP keep-alives may consume 281 significant resources both in the network and in endpoints (e.g., 282 battery power). In addition, frequent keep-alives risk network 283 congestion. The higher the frequency of keep-alives, the higher the 284 overhead. 286 Given the cost of keep-alives, parameters have to be configured 287 carefully: 289 * The default idle interval (leaf "idle-time") MUST default to no 290 less than two hours, i.e., 7200 seconds [RFC1122]. A lower value 291 MAY be configured, but keep-alive messages SHOULD NOT be 292 transmitted more frequently than once every 15 seconds. Longer 293 intervals SHOULD be used when possible. 295 * The maximum number of sequential keep-alive probes that can fail 296 (leaf "max-probes") trades off responsiveness and robustness 297 against packet loss. ACK segments that contain no data are not 298 reliably transmitted by TCP. Consequently, if a keep-alive 299 mechanism is implemented it MUST NOT interpret failure to respond 300 to any specific probe as a dead connection [RFC1122]. Typically a 301 single-digit number should suffice. 303 * TCP implementations may include a parameter for the number of 304 seconds between TCP keep-alive probes (leaf "probe-interval"). In 305 order to avoid congestion, the time interval between probes MUST 306 NOT be smaller than one second. Significantly longer intervals 307 SHOULD be used. It is important to note that keep-alive probes 308 (or replies) can get dropped due to network congestion. Sending 309 further probe messages into a congested path after a short 310 interval, without backing off timers, could cause harm and result 311 in a congestion collapse. Therefore it is essential to pick a 312 large, conservative value for this interval. 314 2.2. Example Usage 316 This section presents an example showing the "tcp-common-grouping" 317 populated with some data. 319 320 321 15 322 3 323 30 324 325 327 2.3. YANG Module 329 The ietf-tcp-common YANG module references [RFC6991]. 331 file "ietf-tcp-common@2020-07-08.yang" 333 module ietf-tcp-common { 334 yang-version 1.1; 335 namespace "urn:ietf:params:xml:ns:yang:ietf-tcp-common"; 336 prefix tcpcmn; 338 organization 339 "IETF NETCONF (Network Configuration) Working Group and the 340 IETF TCP Maintenance and Minor Extensions (TCPM) Working Group"; 342 contact 343 "WG Web: 344 345 WG List: 346 347 Authors: Kent Watsen 348 Michael Scharf 349 "; 351 description 352 "This module defines reusable groupings for TCP commons that 353 can be used as a basis for specific TCP common instances. 355 Copyright (c) 2020 IETF Trust and the persons identified 356 as authors of the code. All rights reserved. 358 Redistribution and use in source and binary forms, with 359 or without modification, is permitted pursuant to, and 360 subject to the license terms contained in, the Simplified 361 BSD License set forth in Section 4.c of the IETF Trust's 362 Legal Provisions Relating to IETF Documents 363 (https://trustee.ietf.org/license-info). 365 This version of this YANG module is part of RFC DDDD 366 (https://www.rfc-editor.org/info/rfcDDDD); see the RFC 367 itself for full legal notices. 369 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 370 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 371 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 372 are to be interpreted as described in BCP 14 (RFC 2119) 373 (RFC 8174) when, and only when, they appear in all 374 capitals, as shown here."; 376 revision 2020-07-08 { 377 description 378 "Initial version"; 379 reference 380 "RFC DDDD: YANG Groupings for TCP Clients and TCP Servers"; 381 } 383 // Features 384 feature keepalives-supported { 385 description 386 "Indicates that keepalives are supported."; 387 } 389 // Groupings 391 grouping tcp-common-grouping { 392 description 393 "A reusable grouping for configuring TCP parameters common 394 to TCP connections as well as the operating system as a 395 whole."; 396 container keepalives { 397 if-feature "keepalives-supported"; 398 presence 399 "Indicates that keepalives are enabled. Present so that 400 the decendant nodes' 'mandatory true' doesn't imply that 401 this node must be configured."; 402 description 403 "Configures the keep-alive policy, to proactively test the 404 aliveness of the TCP peer. An unresponsive TCP peer is 405 dropped after approximately (idle-time + max-probes 406 * probe-interval) seconds."; 407 leaf idle-time { 408 type uint16 { 409 range "1..max"; 410 } 411 units "seconds"; 412 mandatory true; 413 description 414 "Sets the amount of time after which if no data has been 415 received from the TCP peer, a TCP-level probe message 416 will be sent to test the aliveness of the TCP peer. 417 Two hours (7200 seconds) is safe value, per RFC 1122."; 418 reference 419 "RFC 1122: 420 Requirements for Internet Hosts -- Communication Layers"; 421 } 422 leaf max-probes { 423 type uint16 { 424 range "1..max"; 425 } 426 mandatory true; 427 description 428 "Sets the maximum number of sequential keep-alive probes 429 that can fail to obtain a response from the TCP peer 430 before assuming the TCP peer is no longer alive."; 431 } 432 leaf probe-interval { 433 type uint16 { 434 range "1..max"; 435 } 436 units "seconds"; 437 mandatory true; 438 description 439 "Sets the time interval between failed probes. The interval 440 SHOULD be significantly longer than one second in order to 441 avoid harm on a congested link."; 442 } 443 } // container keepalives 444 } // grouping tcp-common-grouping 446 grouping tcp-connection-grouping { 447 description 448 "A reusable grouping for configuring TCP parameters common 449 to TCP connections."; 450 uses tcp-common-grouping; 451 } 453 } 455 457 3. The "ietf-tcp-client" Module 459 3.1. Data Model Overview 461 3.1.1. Features 463 The following diagram lists all the "feature" statements defined in 464 the "ietf-tcp-client" module: 466 Features: 467 +-- local-binding-supported 468 +-- tcp-client-keepalives 469 +-- proxy-connect 470 +-- socks5-gss-api 471 +-- socks5-username-password 473 3.1.2. Groupings 475 The following diagram lists all the "grouping" statements defined in 476 the "ietf-tcp-client" module: 478 Groupings: 479 +-- tcp-client-grouping 481 Each of these groupings are presented in the following subsections. 483 3.1.2.1. The "tcp-client-grouping" Grouping 485 The following tree diagram [RFC8340] illustrates the "tcp-client- 486 grouping" grouping: 488 grouping tcp-client-grouping 489 +-- remote-address inet:host 490 +-- remote-port? inet:port-number 491 +-- local-address? inet:ip-address 492 | {local-binding-supported}? 493 +-- local-port? inet:port-number 494 | {local-binding-supported}? 495 +-- proxy-server! {proxy-connect}? 496 | +-- (proxy-type) 497 | +--:(socks4) 498 | | +-- socks4-parameters 499 | | +-- remote-address inet:ip-address 500 | | +-- remote-port? inet:port-number 501 | +--:(socks4a) 502 | | +-- socks4a-parameters 503 | | +-- remote-address inet:host 504 | | +-- remote-port? inet:port-number 505 | +--:(socks5) 506 | +-- socks5-parameters 507 | +-- remote-address inet:host 508 | +-- remote-port? inet:port-number 509 | +-- authentication-parameters! 510 | +-- (auth-type) 511 | +--:(gss-api) {socks5-gss-api}? 512 | | +-- gss-api 513 | +--:(username-password) 514 | {socks5-username-password}? 515 | +-- username-password 516 | +-- username? string 517 | +-- password? string 518 +---u tcpcmn:tcp-connection-grouping 520 Comments: 522 * The "remote-address" node, which is mandatory, may be configured 523 as an IPv4 address, an IPv6 address, a hostname. 525 * The "remote-port" node is not mandatory, but its default value is 526 the invalid value '0', thus forcing the consuming data model to 527 refine it in order to provide it an appropriate default value. 529 * The "local-address" node, which is enabled by the "local-binding- 530 supported" feature (Section 2.1.2), may be configured as an IPv4 531 address, an IPv6 address, or a wildcard value. 533 * The "local-port" node, which is enabled by the "local-binding- 534 supported" feature (Section 2.1.2), is not mandatory. Its default 535 value is '0', indicating that the operating system can pick an 536 arbitrary port number. 538 * The "proxy-server" node is enabled by a "feature" statement and, 539 for servers that enable it, is a "presence" container so that the 540 decendent "mandatory true" choice node doesn't imply that the 541 proxt-server node must be configured. 543 * This grouping uses the "tcp-connection-grouping" grouping 544 discussed in Section 2.1.3.2. 546 3.1.3. Protocol-accessible Nodes 548 The "ietf-tcp-client" module does not contain any protocol-accessible 549 nodes. 551 3.2. Example Usage 553 This section presents an example showing the "tcp-client-grouping" 554 populated with some data. 556 557 www.example.com 558 443 559 0.0.0.0 560 0 561 562 15 563 3 564 30 565 566 568 3.3. YANG Module 570 The ietf-tcp-client YANG module references [RFC6991]. 572 file "ietf-tcp-client@2020-07-08.yang" 574 module ietf-tcp-client { 575 yang-version 1.1; 576 namespace "urn:ietf:params:xml:ns:yang:ietf-tcp-client"; 577 prefix tcpc; 579 import ietf-inet-types { 580 prefix inet; 581 reference 582 "RFC 6991: Common YANG Data Types"; 583 } 585 import ietf-netconf-acm { 586 prefix nacm; 587 reference 588 "RFC 8341: Network Configuration Access Control Model"; 589 } 591 import ietf-tcp-common { 592 prefix tcpcmn; 593 reference 594 "RFC DDDD: YANG Groupings for TCP Clients and TCP Servers"; 595 } 597 organization 598 "IETF NETCONF (Network Configuration) Working Group and the 599 IETF TCP Maintenance and Minor Extensions (TCPM) Working Group"; 601 contact 602 "WG Web: 603 604 WG List: 605 606 Authors: Kent Watsen 607 Michael Scharf 608 "; 610 description 611 "This module defines reusable groupings for TCP clients that 612 can be used as a basis for specific TCP client instances. 614 Copyright (c) 2020 IETF Trust and the persons identified 615 as authors of the code. All rights reserved. 617 Redistribution and use in source and binary forms, with 618 or without modification, is permitted pursuant to, and 619 subject to the license terms contained in, the Simplified 620 BSD License set forth in Section 4.c of the IETF Trust's 621 Legal Provisions Relating to IETF Documents 622 (https://trustee.ietf.org/license-info). 624 This version of this YANG module is part of RFC DDDD 625 (https://www.rfc-editor.org/info/rfcDDDD); see the RFC 626 itself for full legal notices. 628 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 629 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 630 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 631 are to be interpreted as described in BCP 14 (RFC 2119) 632 (RFC 8174) when, and only when, they appear in all 633 capitals, as shown here."; 635 revision 2020-07-08 { 636 description 637 "Initial version"; 638 reference 639 "RFC DDDD: YANG Groupings for TCP Clients and TCP Servers"; 640 } 642 // Features 644 feature local-binding-supported { 645 description 646 "Indicates that the server supports configuring local 647 bindings (i.e., the local address and local port) for 648 TCP clients."; 649 } 651 feature tcp-client-keepalives { 652 description 653 "Per socket TCP keepalive parameters are configurable for 654 TCP clients on the server implementing this feature."; 655 } 657 feature proxy-connect { 658 description 659 "Proxy connection configuration is configurable for 660 TCP clients on the server implementing this feature."; 661 } 663 feature socks5-gss-api { 664 description 665 "Indicates that the server supports authenticating 666 using GSSAPI when initiating TCP connections via 667 and SOCKS Version 5 proxy server."; 668 reference 669 "RFC 1928: SOCKS Protocol Version 5"; 670 } 672 feature socks5-username-password { 673 description 674 "Indicates that the server supports authenticating 675 using username/password when initiating TCP 676 connections via and SOCKS Version 5 proxy 677 server."; 678 reference 679 "RFC 1928: SOCKS Protocol Version 5"; 680 } 682 // Groupings 684 grouping tcp-client-grouping { 685 description 686 "A reusable grouping for configuring a TCP client. 688 Note that this grouping uses fairly typical descendent 689 node names such that a stack of 'uses' statements will 690 have name conflicts. It is intended that the consuming 691 data model will resolve the issue (e.g., by wrapping 692 the 'uses' statement in a container called 693 'tcp-client-parameters'). This model purposely does 694 not do this itself so as to provide maximum flexibility 695 to consuming models."; 697 leaf remote-address { 698 type inet:host; 699 mandatory true; 700 description 701 "The IP address or hostname of the remote peer to 702 establish a connection with. If a domain name is 703 configured, then the DNS resolution should happen on 704 each connection attempt. If the DNS resolution 705 results in multiple IP addresses, the IP addresses 706 are tried according to local preference order until 707 a connection has been established or until all IP 708 addresses have failed."; 709 } 710 leaf remote-port { 711 type inet:port-number; 712 default "0"; 713 description 714 "The IP port number for the remote peer to establish a 715 connection with. An invalid default value (0) is used 716 (instead of 'mandatory true') so that as application 717 level data model may 'refine' it with an application 718 specific default port number value."; 719 } 720 leaf local-address { 721 if-feature "local-binding-supported"; 722 type inet:ip-address; 723 description 724 "The local IP address/interface (VRF?) to bind to for when 725 connecting to the remote peer. INADDR_ANY ('0.0.0.0') or 726 INADDR6_ANY ('0:0:0:0:0:0:0:0' a.k.a. '::') MAY be used to 727 explicitly indicate the implicit default, that the server 728 can bind to any IPv4 or IPv6 addresses, respectively."; 729 } 730 leaf local-port { 731 if-feature "local-binding-supported"; 732 type inet:port-number; 733 default "0"; 734 description 735 "The local IP port number to bind to for when connecting 736 to the remote peer. The port number '0', which is the 737 default value, indicates that any available local port 738 number may be used."; 739 } 741 container proxy-server { 742 if-feature "proxy-connect"; 743 presence 744 "Indicates that a proxy connection is configured. 745 Present so that the 'proxy-type' node's 'mandatory 746 true' doesn't imply that the proxy connection 747 must be configured."; 748 choice proxy-type { 749 mandatory true; 750 description 751 "Selects a proxy connection protocol."; 752 case socks4 { 753 container socks4-parameters { 754 leaf remote-address { 755 type inet:ip-address; 756 mandatory true; 757 description 758 "The IP address of the proxy server."; 759 } 760 leaf remote-port { 761 type inet:port-number; 762 default "1080"; 763 description 764 "The IP port number for the proxy server."; 765 } 766 description 767 "Parameters for connecting to a TCP-based proxy 768 server using the SOCKS4 protocol."; 769 reference 770 "SOCKS, Proceedings: 1992 Usenix Security Symposium."; 771 } 772 } 773 case socks4a { 774 container socks4a-parameters { 775 leaf remote-address { 776 type inet:host; 777 mandatory true; 778 description 779 "The IP address or hostname of the proxy server."; 780 } 781 leaf remote-port { 782 type inet:port-number; 783 default "1080"; 784 description 785 "The IP port number for the proxy server."; 786 } 787 description 788 "Parameters for connecting to a TCP-based proxy 789 server using the SOCKS4a protocol."; 790 reference 791 "SOCKS Proceedings: 792 1992 Usenix Security Symposium. 793 OpenSSH message: 794 SOCKS 4A: A Simple Extension to SOCKS 4 Protocol 795 https://www.openssh.com/txt/socks4a.protocol"; 796 } 797 } 798 case socks5 { 799 container socks5-parameters { 800 leaf remote-address { 801 type inet:host; 802 mandatory true; 803 description 804 "The IP address or hostname of the proxy server."; 805 } 806 leaf remote-port { 807 type inet:port-number; 808 default "1080"; 809 description 810 "The IP port number for the proxy server."; 811 } 812 container authentication-parameters { 813 presence 814 "Indicates that an authentication mechanism 815 has been configured. Present so that the 816 'auth-type' node's 'mandatory true' doesn't 817 imply that an authentication mechanism 818 must be configured."; 819 description 820 "A container for SOCKS Version 5 authentication 821 mechanisms. 823 A complete list of methods is defined at: 824 https://www.iana.org/assignments/socks-methods 825 /socks-methods.xhtml."; 826 reference 827 "RFC 1928: SOCKS Protocol Version 5"; 828 choice auth-type { 829 mandatory true; 830 description 831 "A choice amongst supported SOCKS Version 5 832 authentication mechanisms."; 833 case gss-api { 834 if-feature socks5-gss-api; 835 container gss-api { 836 description 837 "Contains GSS-API configuration. Defines 838 as an empty container to enable specific 839 GSS-API configuration to be augmented in 840 by future modules."; 841 reference 842 "RFC 1928: SOCKS Protocol Version 5 843 RFC 2743: Generic Security Service 844 Application Program Interface 845 Version 2, Update 1"; 846 } 847 } 848 case username-password { 849 if-feature socks5-username-password; 850 container username-password { 851 leaf username { 852 type string; 853 description 854 "The 'username' value to use."; 855 } 856 leaf password { 857 nacm:default-deny-all; 858 type string; 859 description 860 "The 'password' value to use."; 861 } 862 description 863 "Contains Username/Password configuration."; 864 reference 865 "RFC 1929: Username/Password Authentication 866 for SOCKS V5"; 867 } 868 } 870 } 871 } 872 description 873 "Parameters for connecting to a TCP-based proxy server 874 using the SOCKS5 protocol."; 875 reference 876 "RFC 1928: SOCKS Protocol Version 5"; 877 } 878 } 879 } 880 description 881 "Proxy server settings."; 882 } 884 uses tcpcmn:tcp-connection-grouping { 885 augment "keepalives" { 886 if-feature "tcp-client-keepalives"; 887 description 888 "Add an if-feature statement so that implementations 889 can choose to support TCP client keepalives."; 890 } 891 } 892 } 893 } 895 897 4. The "ietf-tcp-server" Module 899 4.1. Data Model Overview 901 4.1.1. Features 903 The following diagram lists all the "feature" statements defined in 904 the "ietf-tcp-server" module: 906 Features: 907 +-- tcp-server-keepalives 909 4.1.2. Groupings 911 The following diagram lists all the "grouping" statements defined in 912 the "ietf-tcp-server" module: 914 Groupings: 915 +-- tcp-server-grouping 917 Each of these groupings are presented in the following subsections. 919 4.1.2.1. The "tcp-server-grouping" Grouping 921 The following tree diagram [RFC8340] illustrates the "tcp-server- 922 grouping" grouping: 924 grouping tcp-server-grouping 925 +-- local-address inet:ip-address 926 +-- local-port? inet:port-number 927 +---u tcpcmn:tcp-connection-grouping 929 Comments: 931 * The "local-address" node, which is mandatory, may be configured as 932 an IPv4 address, an IPv6 address, or a wildcard value. 934 * The "local-port" node is not mandatory, but its default value is 935 the invalid value '0', thus forcing the consuming data model to 936 refine it in order to provide it an appropriate default value. 938 * This grouping uses the "tcp-connection-grouping" grouping 939 discussed in Section 2.1.3.2. 941 4.1.3. Protocol-accessible Nodes 943 The "ietf-tcp-server" module does not contain any protocol-accessible 944 nodes. 946 4.2. Example Usage 948 This section presents an example showing the "tcp-server-grouping" 949 populated with some data. 951 952 10.20.30.40 953 7777 954 955 15 956 3 957 30 958 959 961 4.3. YANG Module 963 The ietf-tcp-server YANG module references [RFC6991]. 965 file "ietf-tcp-server@2020-07-08.yang" 966 module ietf-tcp-server { 967 yang-version 1.1; 968 namespace "urn:ietf:params:xml:ns:yang:ietf-tcp-server"; 969 prefix tcps; 971 import ietf-inet-types { 972 prefix inet; 973 reference 974 "RFC 6991: Common YANG Data Types"; 975 } 977 import ietf-tcp-common { 978 prefix tcpcmn; 979 reference 980 "RFC DDDD: YANG Groupings for TCP Clients and TCP Servers"; 981 } 983 organization 984 "IETF NETCONF (Network Configuration) Working Group and the 985 IETF TCP Maintenance and Minor Extensions (TCPM) Working Group"; 987 contact 988 "WG Web: 989 990 WG List: 991 992 Authors: Kent Watsen 993 Michael Scharf 994 "; 996 description 997 "This module defines reusable groupings for TCP servers that 998 can be used as a basis for specific TCP server instances. 1000 Copyright (c) 2020 IETF Trust and the persons identified 1001 as authors of the code. All rights reserved. 1003 Redistribution and use in source and binary forms, with 1004 or without modification, is permitted pursuant to, and 1005 subject to the license terms contained in, the Simplified 1006 BSD License set forth in Section 4.c of the IETF Trust's 1007 Legal Provisions Relating to IETF Documents 1008 (https://trustee.ietf.org/license-info). 1010 This version of this YANG module is part of RFC DDDD 1011 (https://www.rfc-editor.org/info/rfcDDDD); see the RFC 1012 itself for full legal notices. 1014 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1015 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 1016 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 1017 are to be interpreted as described in BCP 14 (RFC 2119) 1018 (RFC 8174) when, and only when, they appear in all 1019 capitals, as shown here."; 1021 revision 2020-07-08 { 1022 description 1023 "Initial version"; 1024 reference 1025 "RFC DDDD: YANG Groupings for TCP Clients and TCP Servers"; 1026 } 1028 // Features 1030 feature tcp-server-keepalives { 1031 description 1032 "Per socket TCP keepalive parameters are configurable for 1033 TCP servers on the server implementing this feature."; 1034 } 1036 // Groupings 1038 grouping tcp-server-grouping { 1039 description 1040 "A reusable grouping for configuring a TCP server. 1042 Note that this grouping uses fairly typical descendent 1043 node names such that a stack of 'uses' statements will 1044 have name conflicts. It is intended that the consuming 1045 data model will resolve the issue (e.g., by wrapping 1046 the 'uses' statement in a container called 1047 'tcp-server-parameters'). This model purposely does 1048 not do this itself so as to provide maximum flexibility 1049 to consuming models."; 1050 leaf local-address { 1051 type inet:ip-address; 1052 mandatory true; 1053 description 1054 "The local IP address to listen on for incoming 1055 TCP client connections. INADDR_ANY (0.0.0.0) or 1056 INADDR6_ANY (0:0:0:0:0:0:0:0 a.k.a. ::) MUST be 1057 used when the server is to listen on all IPv4 or 1058 IPv6 addresses, respectively."; 1059 } 1060 leaf local-port { 1061 type inet:port-number; 1062 default "0"; 1063 description 1064 "The local port number to listen on for incoming TCP 1065 client connections. An invalid default value (0) 1066 is used (instead of 'mandatory true') so that an 1067 application level data model may 'refine' it with 1068 an application specific default port number value."; 1069 } 1070 uses tcpcmn:tcp-connection-grouping { 1071 augment "keepalives" { 1072 if-feature "tcp-server-keepalives"; 1073 description 1074 "Add an if-feature statement so that implementations 1075 can choose to support TCP server keepalives."; 1076 } 1077 } 1078 } 1079 } 1081 1083 5. Security Considerations 1085 5.1. The "ietf-tcp-common" YANG Module 1087 The "ietf-tcp-common" YANG module defines "grouping" statements that 1088 are designed to be accessed via YANG based management protocols, such 1089 as NETCONF [RFC6241] and RESTCONF [RFC8040]. Both of these protocols 1090 have mandatory-to-implement secure transport layers (e.g., SSH, TLS) 1091 with mutual authentication. 1093 The NETCONF access control model (NACM) [RFC8341] provides the means 1094 to restrict access for particular users to a pre-configured subset of 1095 all available protocol operations and content. 1097 Since the module in this document only define groupings, these 1098 considerations are primarily for the designers of other modules that 1099 use these groupings. 1101 None of the readable data nodes defined in this YANG module are 1102 considered sensitive or vulnerable in network environments. The NACM 1103 "default-deny-all" extension has not been set for any data nodes 1104 defined in this module. 1106 None of the writable data nodes defined in this YANG module are 1107 considered sensitive or vulnerable in network environments. The NACM 1108 "default-deny-write" extension has not been set for any data nodes 1109 defined in this module. 1111 This module does not define any RPCs, actions, or notifications, and 1112 thus the security consideration for such is not provided here. 1114 5.2. The "ietf-tcp-client" YANG Module 1116 The "ietf-tcp-client" YANG module defines "grouping" statements that 1117 are designed to be accessed via YANG based management protocols, such 1118 as NETCONF [RFC6241] and RESTCONF [RFC8040]. Both of these protocols 1119 have mandatory-to-implement secure transport layers (e.g., SSH, TLS) 1120 with mutual authentication. 1122 The NETCONF access control model (NACM) [RFC8341] provides the means 1123 to restrict access for particular users to a pre-configured subset of 1124 all available protocol operations and content. 1126 Since the module in this document only define groupings, these 1127 considerations are primarily for the designers of other modules that 1128 use these groupings. 1130 One readable data node defined in this YANG module may be considered 1131 sensitive or vulnerable in some network environments. This node is 1132 as follows: 1134 * The "proxy-server/socks5-parameters/authentication-parameters/ 1135 username-password/password" node: 1137 The cleartext "password" node defined in the "tcp-client- 1138 grouping" grouping is additionally sensitive to read operations 1139 such that, in normal use cases, it should never be returned to 1140 a client. For this reason, the NACM extension "default-deny- 1141 all" has been applied to it. 1143 None of the writable data nodes defined in this YANG module are 1144 considered sensitive or vulnerable in network environments. The NACM 1145 "default-deny-write" extension has not been set for any data nodes 1146 defined in this module. 1148 This module does not define any RPCs, actions, or notifications, and 1149 thus the security consideration for such is not provided here. 1151 5.3. The "ietf-tcp-server" YANG Module 1153 The "ietf-tcp-server" YANG module defines "grouping" statements that 1154 are designed to be accessed via YANG based management protocols, such 1155 as NETCONF [RFC6241] and RESTCONF [RFC8040]. Both of these protocols 1156 have mandatory-to-implement secure transport layers (e.g., SSH, TLS) 1157 with mutual authentication. 1159 The NETCONF access control model (NACM) [RFC8341] provides the means 1160 to restrict access for particular users to a pre-configured subset of 1161 all available protocol operations and content. 1163 Since the module in this document only define groupings, these 1164 considerations are primarily for the designers of other modules that 1165 use these groupings. 1167 None of the readable data nodes defined in this YANG module are 1168 considered sensitive or vulnerable in network environments. The NACM 1169 "default-deny-all" extension has not been set for any data nodes 1170 defined in this module. 1172 None of the writable data nodes defined in this YANG module are 1173 considered sensitive or vulnerable in network environments. The NACM 1174 "default-deny-write" extension has not been set for any data nodes 1175 defined in this module. 1177 This module does not define any RPCs, actions, or notifications, and 1178 thus the security consideration for such is not provided here. 1180 6. IANA Considerations 1182 6.1. The IETF XML Registry 1184 This document registers two URIs in the "ns" subregistry of the IETF 1185 XML Registry [RFC3688]. Following the format in [RFC3688], the 1186 following registrations are requested: 1188 URI: urn:ietf:params:xml:ns:yang:ietf-tcp-client 1189 Registrant Contact: The NETCONF WG of the IETF. 1190 XML: N/A, the requested URI is an XML namespace. 1192 URI: urn:ietf:params:xml:ns:yang:ietf-tcp-server 1193 Registrant Contact: The NETCONF WG of the IETF. 1194 XML: N/A, the requested URI is an XML namespace. 1196 6.2. The YANG Module Names Registry 1198 This document registers two YANG modules in the YANG Module Names 1199 registry [RFC6020]. Following the format in [RFC6020], the following 1200 registrations are requested: 1202 name: ietf-tcp-common 1203 namespace: urn:ietf:params:xml:ns:yang:ietf-tcp-common 1204 prefix: tcpcmn 1205 reference: RFC DDDD 1207 name: ietf-tcp-client 1208 namespace: urn:ietf:params:xml:ns:yang:ietf-tcp-client 1209 prefix: tcpc 1210 reference: RFC DDDD 1212 name: ietf-tcp-server 1213 namespace: urn:ietf:params:xml:ns:yang:ietf-tcp-server 1214 prefix: tcps 1215 reference: RFC DDDD 1217 7. References 1219 7.1. Normative References 1221 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1222 Requirement Levels", BCP 14, RFC 2119, 1223 DOI 10.17487/RFC2119, March 1997, 1224 . 1226 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1227 the Network Configuration Protocol (NETCONF)", RFC 6020, 1228 DOI 10.17487/RFC6020, October 2010, 1229 . 1231 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 1232 RFC 6991, DOI 10.17487/RFC6991, July 2013, 1233 . 1235 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1236 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1237 . 1239 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1240 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1241 May 2017, . 1243 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 1244 Access Control Model", STD 91, RFC 8341, 1245 DOI 10.17487/RFC8341, March 2018, 1246 . 1248 7.2. Informative References 1250 [I-D.ietf-netconf-crypto-types] 1251 Watsen, K., "Common YANG Data Types for Cryptography", 1252 Work in Progress, Internet-Draft, draft-ietf-netconf- 1253 crypto-types-15, 20 May 2020, 1254 . 1257 [I-D.ietf-netconf-http-client-server] 1258 Watsen, K., "YANG Groupings for HTTP Clients and HTTP 1259 Servers", Work in Progress, Internet-Draft, draft-ietf- 1260 netconf-http-client-server-03, 20 May 2020, 1261 . 1264 [I-D.ietf-netconf-keystore] 1265 Watsen, K., "A YANG Data Model for a Keystore", Work in 1266 Progress, Internet-Draft, draft-ietf-netconf-keystore-17, 1267 20 May 2020, . 1270 [I-D.ietf-netconf-netconf-client-server] 1271 Watsen, K., "NETCONF Client and Server Models", Work in 1272 Progress, Internet-Draft, draft-ietf-netconf-netconf- 1273 client-server-19, 20 May 2020, 1274 . 1277 [I-D.ietf-netconf-restconf-client-server] 1278 Watsen, K., "RESTCONF Client and Server Models", Work in 1279 Progress, Internet-Draft, draft-ietf-netconf-restconf- 1280 client-server-19, 20 May 2020, 1281 . 1284 [I-D.ietf-netconf-ssh-client-server] 1285 Watsen, K. and G. Wu, "YANG Groupings for SSH Clients and 1286 SSH Servers", Work in Progress, Internet-Draft, draft- 1287 ietf-netconf-ssh-client-server-19, 20 May 2020, 1288 . 1291 [I-D.ietf-netconf-tcp-client-server] 1292 Watsen, K. and M. Scharf, "YANG Groupings for TCP Clients 1293 and TCP Servers", Work in Progress, Internet-Draft, draft- 1294 ietf-netconf-tcp-client-server-06, 16 June 2020, 1295 . 1298 [I-D.ietf-netconf-tls-client-server] 1299 Watsen, K. and G. Wu, "YANG Groupings for TLS Clients and 1300 TLS Servers", Work in Progress, Internet-Draft, draft- 1301 ietf-netconf-tls-client-server-19, 20 May 2020, 1302 . 1305 [I-D.ietf-netconf-trust-anchors] 1306 Watsen, K., "A YANG Data Model for a Truststore", Work in 1307 Progress, Internet-Draft, draft-ietf-netconf-trust- 1308 anchors-10, 20 May 2020, . 1311 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1312 DOI 10.17487/RFC3688, January 2004, 1313 . 1315 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1316 and A. Bierman, Ed., "Network Configuration Protocol 1317 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1318 . 1320 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1321 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1322 . 1324 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1325 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1326 . 1328 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1329 and R. Wilton, "Network Management Datastore Architecture 1330 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 1331 . 1333 Appendix A. Change Log 1335 This section is to be removed before publishing as an RFC. 1337 A.1. 00 to 01 1338 * Added 'local-binding-supported' feature to TCP-client model. 1340 * Added 'keepalives-supported' feature to TCP-common model. 1342 * Added 'external-endpoint-values' container and 'external- 1343 endpoints' feature to TCP-server model. 1345 A.2. 01 to 02 1347 * Removed the 'external-endpoint-values' container and 'external- 1348 endpoints' feature from the TCP-server model. 1350 A.3. 02 to 03 1352 * Moved the common model section to be before the client and server 1353 specific sections. 1355 * Added sections "Model Scope" and "Usage Guidelines for Configuring 1356 TCP Keep-Alives" to the common model section. 1358 A.4. 03 to 04 1360 * Fixed a few typos. 1362 A.5. 04 to 05 1364 * Removed commented out "grouping tcp-system-grouping" statement 1365 kept for reviewers. 1367 * Added a "Note to Reviewers" note to first page. 1369 A.6. 05 to 06 1371 * Added support for TCP proxies. 1373 A.7. 06 to 07 1375 * Expanded "Data Model Overview section(s) [remove "wall" of tree 1376 diagrams]. 1378 * Updated the Security Considerations section. 1380 Authors' Addresses 1382 Kent Watsen 1383 Watsen Networks 1385 Email: kent+ietf@watsen.net 1386 Michael Scharf 1387 Hochschule Esslingen - University of Applied Sciences 1389 Email: michael.scharf@hs-esslingen.de