idnits 2.17.1 draft-ietf-netconf-tcp-client-server-06.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 254 has weird spacing: '...nterval uin...' == Line 259 has weird spacing: '...nterval uin...' == Line 410 has weird spacing: '...address ine...' == Line 418 has weird spacing: '...address ine...' == Line 422 has weird spacing: '...address ine...' == (3 more instances...) -- The document date (June 16, 2020) is 1408 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 1064 -- Looks like a reference, but probably isn't: '2' on line 1066 -- Looks like a reference, but probably isn't: '3' on line 1068 -- Looks like a reference, but probably isn't: '4' on line 1070 -- Looks like a reference, but probably isn't: '5' on line 1072 -- Looks like a reference, but probably isn't: '6' on line 1074 -- Looks like a reference, but probably isn't: '7' on line 1076 -- Looks like a reference, but probably isn't: '8' on line 1078 -- Looks like a reference, but probably isn't: '9' on line 1081 == Missing Reference: 'RFC1122' is mentioned on line 229, but not defined == Missing Reference: 'RFC793bis' is mentioned on line 195, 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: December 18, 2020 Hochschule Esslingen 6 June 16, 2020 8 YANG Groupings for TCP Clients and TCP Servers 9 draft-ietf-netconf-tcp-client-server-06 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-06-16" --> 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 December 18, 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 . . . . . . . . . . . . . . . . . . . . . . 10 137 4.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 11 138 5. The TCP Server Model . . . . . . . . . . . . . . . . . . . . 18 139 5.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 18 140 5.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 18 141 5.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 18 142 6. Security Considerations . . . . . . . . . . . . . . . . . . . 21 143 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 144 7.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 22 145 7.2. The YANG Module Names Registry . . . . . . . . . . . . . 22 146 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 22 147 8.1. Normative References . . . . . . . . . . . . . . . . . . 22 148 8.2. Informative References . . . . . . . . . . . . . . . . . 23 149 8.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 23 150 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 25 151 A.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 25 152 A.2. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 25 153 A.3. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 25 154 A.4. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 25 155 A.5. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 25 156 A.6. 05 to 06 . . . . . . . . . . . . . . . . . . . . . . . . 25 157 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 25 159 1. Introduction 161 This document defines three YANG 1.1 [RFC7950] modules: the first 162 defines a grouping for configuring a generic TCP client, the second 163 defines a grouping for configuring a generic TCP server, and the 164 third defines a grouping common to the TCP clients and TCP servers. 166 It is intended that these groupings will be used either standalone, 167 for TCP-based protocols, as part of a stack of protocol-specific 168 configuration models. For instance, these groupings could help 169 define the configuration module for SSH, TLS, or HTTP based 170 applications. 172 2. Terminology 174 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 175 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 176 "OPTIONAL" in this document are to be interpreted as described in BCP 177 14 [RFC2119] [RFC8174] when, and only when, they appear in all 178 capitals, as shown here. 180 3. The TCP Common Model 182 3.1. Model Scope 184 This document defines a common "grouping" statement for basic TCP 185 connection parameters that matter to applications. In some TCP 186 stacks, such parameters can also directly be set by an application 187 using system calls, such as the socket API. The base YANG model in 188 this document focuses on modeling TCP keep-alives. This base model 189 can be extended as needed. 191 3.2. Usage Guidelines for Configuring TCP Keep-Alives 193 Network stacks may include "keep-alives" in their TCP 194 implementations, although this practice is not universally accepted. 195 If keep-alives are included, [RFC1122] [RFC793bis] mandates that the 196 application MUST be able to turn them on or off for each TCP 197 connection, and that they MUST default to off. 199 Keep-alive mechanisms exist in many protocols. Depending on the 200 protocol stack, TCP keep-alives may only be one out of several 201 alternatives. Which mechanism(s) to use depends on the use case and 202 application requirements. If keep-alives are needed by an 203 application, it is RECOMMENDED that the aliveness check happens only 204 at the protocol layers that are meaningful to the application. 206 A TCP keep-alive mechanism SHOULD only be invoked in server 207 applications that might otherwise hang indefinitely and consume 208 resources unnecessarily if a client crashes or aborts a connection 209 during a network failure [RFC1122]. TCP keep-alives may consume 210 significant resources both in the network and in endpoints (e.g., 211 battery power). In addition, frequent keep-alives risk network 212 congestion. The higher the frequency of keep-alives, the higher the 213 overhead. 215 Given the cost of keep-alives, parameters have to be configured 216 carefully: 218 o The default idle interval (leaf "idle-time") MUST default to no 219 less than two hours, i.e., 7200 seconds [RFC1122]. A lower value 220 MAY be configured, but keep-alive messages SHOULD NOT be 221 transmitted more frequently than once every 15 seconds. Longer 222 intervals SHOULD be used when possible. 224 o The maximum number of sequential keep-alive probes that can fail 225 (leaf "max-probes") trades off responsiveness and robustness 226 against packet loss. ACK segments that contain no data are not 227 reliably transmitted by TCP. Consequently, if a keep-alive 228 mechanism is implemented it MUST NOT interpret failure to respond 229 to any specific probe as a dead connection [RFC1122]. Typically a 230 single-digit number should suffice. 232 o TCP implementations may include a parameter for the number of 233 seconds between TCP keep-alive probes (leaf "probe-interval"). In 234 order to avoid congestion, the time interval between probes MUST 235 NOT be smaller than one second. Significantly longer intervals 236 SHOULD be used. It is important to note that keep-alive probes 237 (or replies) can get dropped due to network congestion. Sending 238 further probe messages into a congested path after a short 239 interval, without backing off timers, could cause harm and result 240 in a congestion collapse. Therefore it is essential to pick a 241 large, conservative value for this interval. 243 3.3. Tree Diagram 245 This section provides a tree diagram [RFC8340] for the "ietf-tcp- 246 common" module. 248 module: ietf-tcp-common 250 grouping tcp-common-grouping 251 +-- keepalives! {keepalives-supported}? 252 +-- idle-time uint16 253 +-- max-probes uint16 254 +-- probe-interval uint16 255 grouping tcp-connection-grouping 256 +-- keepalives! {keepalives-supported}? 257 +-- idle-time uint16 258 +-- max-probes uint16 259 +-- probe-interval uint16 261 3.4. Example Usage 263 This section presents an example showing the "tcp-common-grouping" 264 populated with some data. 266 267 268 15 269 3 270 30 271 272 274 3.5. YANG Module 276 The ietf-tcp-common YANG module references [RFC6991]. 278 file "ietf-tcp-common@2020-06-16.yang" 280 module ietf-tcp-common { 281 yang-version 1.1; 282 namespace "urn:ietf:params:xml:ns:yang:ietf-tcp-common"; 283 prefix tcpcmn; 284 organization 285 "IETF NETCONF (Network Configuration) Working Group and the 286 IETF TCP Maintenance and Minor Extensions (TCPM) Working Group"; 288 contact 289 "WG Web: 290 291 WG List: 292 293 Authors: Kent Watsen 294 Michael Scharf 295 "; 297 description 298 "This module defines reusable groupings for TCP commons that 299 can be used as a basis for specific TCP common instances. 301 Copyright (c) 2020 IETF Trust and the persons identified 302 as authors of the code. All rights reserved. 304 Redistribution and use in source and binary forms, with 305 or without modification, is permitted pursuant to, and 306 subject to the license terms contained in, the Simplified 307 BSD License set forth in Section 4.c of the IETF Trust's 308 Legal Provisions Relating to IETF Documents 309 (https://trustee.ietf.org/license-info). 311 This version of this YANG module is part of RFC DDDD 312 (https://www.rfc-editor.org/info/rfcDDDD); see the RFC 313 itself for full legal notices. 315 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 316 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 317 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 318 are to be interpreted as described in BCP 14 (RFC 2119) 319 (RFC 8174) when, and only when, they appear in all 320 capitals, as shown here."; 322 revision 2020-06-16 { 323 description 324 "Initial version"; 325 reference 326 "RFC DDDD: YANG Groupings for TCP Clients and TCP Servers"; 327 } 329 // Features 330 feature keepalives-supported { 331 description 332 "Indicates that keepalives are supported."; 333 } 335 // Groupings 337 grouping tcp-common-grouping { 338 description 339 "A reusable grouping for configuring TCP parameters common 340 to TCP connections as well as the operating system as a 341 whole."; 342 container keepalives { 343 if-feature "keepalives-supported"; 344 presence "Indicates that keepalives are enabled."; 345 description 346 "Configures the keep-alive policy, to proactively test the 347 aliveness of the TCP peer. An unresponsive TCP peer is 348 dropped after approximately (idle-time + max-probes 349 * probe-interval) seconds."; 350 leaf idle-time { 351 type uint16 { 352 range "1..max"; 353 } 354 units "seconds"; 355 mandatory true; 356 description 357 "Sets the amount of time after which if no data has been 358 received from the TCP peer, a TCP-level probe message 359 will be sent to test the aliveness of the TCP peer. 360 Two hours (7200 seconds) is safe value, per RFC 1122."; 361 reference 362 "RFC 1122: 363 Requirements for Internet Hosts -- Communication Layers"; 364 } 365 leaf max-probes { 366 type uint16 { 367 range "1..max"; 368 } 369 mandatory true; 370 description 371 "Sets the maximum number of sequential keep-alive probes 372 that can fail to obtain a response from the TCP peer 373 before assuming the TCP peer is no longer alive."; 374 } 375 leaf probe-interval { 376 type uint16 { 377 range "1..max"; 378 } 379 units "seconds"; 380 mandatory true; 381 description 382 "Sets the time interval between failed probes. The interval 383 SHOULD be significantly longer than one second in order to 384 avoid harm on a congested link."; 385 } 386 } // container keepalives 387 } // grouping tcp-common-grouping 389 grouping tcp-connection-grouping { 390 description 391 "A reusable grouping for configuring TCP parameters common 392 to TCP connections."; 393 uses tcp-common-grouping; 394 } 396 } 398 400 4. The TCP Client Model 402 4.1. Tree Diagram 404 This section provides a tree diagram [RFC8340] for the "ietf-tcp- 405 client" module. 407 module: ietf-tcp-client 409 grouping tcp-client-grouping 410 +-- remote-address inet:host 411 +-- remote-port? inet:port-number 412 +-- local-address? inet:ip-address {local-binding-supported}? 413 +-- local-port? inet:port-number {local-binding-supported}? 414 +-- proxy-server! {proxy-connect}? 415 | +-- (proxy-type) 416 | +--:(socks4) 417 | | +-- socks4-parameters 418 | | +-- remote-address inet:ip-address 419 | | +-- remote-port? inet:port-number 420 | +--:(socks4a) 421 | | +-- socks4a-parameters 422 | | +-- remote-address inet:host 423 | | +-- remote-port? inet:port-number 424 | +--:(socks5) 425 | +-- socks5-parameters 426 | +-- remote-address inet:host 427 | +-- remote-port? inet:port-number 428 | +-- authentication-parameters! 429 | +-- (auth-type) 430 | +--:(gss-api) {socks5-gss-api}? 431 | | +-- gss-api 432 | +--:(username-password) 433 | {socks5-username-password}? 434 | +-- username-password 435 | +-- username? string 436 | +-- password? string 437 +-- keepalives! {keepalives-supported}? 438 +-- idle-time uint16 439 +-- max-probes uint16 440 +-- probe-interval uint16 442 4.2. Example Usage 444 This section presents an example showing the "tcp-client-grouping" 445 populated with some data. 447 448 www.example.com 449 443 450 0.0.0.0 451 0 452 453 15 454 3 455 30 456 457 459 4.3. YANG Module 461 The ietf-tcp-client YANG module references [RFC6991]. 463 file "ietf-tcp-client@2020-06-16.yang" 465 module ietf-tcp-client { 466 yang-version 1.1; 467 namespace "urn:ietf:params:xml:ns:yang:ietf-tcp-client"; 468 prefix tcpc; 470 import ietf-inet-types { 471 prefix inet; 472 reference 473 "RFC 6991: Common YANG Data Types"; 474 } 476 import ietf-tcp-common { 477 prefix tcpcmn; 478 reference 479 "RFC DDDD: YANG Groupings for TCP Clients and TCP Servers"; 480 } 482 organization 483 "IETF NETCONF (Network Configuration) Working Group and the 484 IETF TCP Maintenance and Minor Extensions (TCPM) Working Group"; 486 contact 487 "WG Web: 488 489 WG List: 490 491 Authors: Kent Watsen 492 Michael Scharf 493 "; 495 description 496 "This module defines reusable groupings for TCP clients that 497 can be used as a basis for specific TCP client instances. 499 Copyright (c) 2020 IETF Trust and the persons identified 500 as authors of the code. All rights reserved. 502 Redistribution and use in source and binary forms, with 503 or without modification, is permitted pursuant to, and 504 subject to the license terms contained in, the Simplified 505 BSD License set forth in Section 4.c of the IETF Trust's 506 Legal Provisions Relating to IETF Documents 507 (https://trustee.ietf.org/license-info). 509 This version of this YANG module is part of RFC DDDD 510 (https://www.rfc-editor.org/info/rfcDDDD); see the RFC 511 itself for full legal notices. 513 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 514 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 515 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 516 are to be interpreted as described in BCP 14 (RFC 2119) 517 (RFC 8174) when, and only when, they appear in all 518 capitals, as shown here."; 520 revision 2020-06-16 { 521 description 522 "Initial version"; 523 reference 524 "RFC DDDD: YANG Groupings for TCP Clients and TCP Servers"; 525 } 527 // Features 529 feature local-binding-supported { 530 description 531 "Indicates that the server supports configuring local 532 bindings (i.e., the local address and local port) for 533 TCP clients."; 534 } 536 feature tcp-client-keepalives { 537 description 538 "Per socket TCP keepalive parameters are configurable for 539 TCP clients on the server implementing this feature."; 540 } 542 feature proxy-connect { 543 description 544 "Proxy connection configuration is configurable for 545 TCP clients on the server implementing this feature."; 546 } 548 feature socks5-gss-api { 549 description 550 "Indicates that the server supports authenticating 551 using GSSAPI when initiating TCP connections via 552 and SOCKS Version 5 proxy server."; 553 reference 554 "RFC 1928: SOCKS Protocol Version 5"; 555 } 557 feature socks5-username-password { 558 description 559 "Indicates that the server supports authenticating 560 using username/password when initiating TCP 561 connections via and SOCKS Version 5 proxy 562 server."; 563 reference 564 "RFC 1928: SOCKS Protocol Version 5"; 565 } 567 // Groupings 569 grouping tcp-client-grouping { 570 description 571 "A reusable grouping for configuring a TCP client. 573 Note that this grouping uses fairly typical descendent 574 node names such that a stack of 'uses' statements will 575 have name conflicts. It is intended that the consuming 576 data model will resolve the issue (e.g., by wrapping 577 the 'uses' statement in a container called 578 'tcp-client-parameters'). This model purposely does 579 not do this itself so as to provide maximum flexibility 580 to consuming models."; 582 leaf remote-address { 583 type inet:host; 584 mandatory true; 585 description 586 "The IP address or hostname of the remote peer to 587 establish a connection with. If a domain name is 588 configured, then the DNS resolution should happen on 589 each connection attempt. If the DNS resolution 590 results in multiple IP addresses, the IP addresses 591 are tried according to local preference order until 592 a connection has been established or until all IP 593 addresses have failed."; 594 } 595 leaf remote-port { 596 type inet:port-number; 597 default "0"; 598 description 599 "The IP port number for the remote peer to establish a 600 connection with. An invalid default value (0) is used 601 (instead of 'mandatory true') so that as application 602 level data model may 'refine' it with an application 603 specific default port number value."; 604 } 605 leaf local-address { 606 if-feature "local-binding-supported"; 607 type inet:ip-address; 608 description 609 "The local IP address/interface (VRF?) to bind to for when 610 connecting to the remote peer. INADDR_ANY ('0.0.0.0') or 611 INADDR6_ANY ('0:0:0:0:0:0:0:0' a.k.a. '::') MAY be used to 612 explicitly indicate the implicit default, that the server 613 can bind to any IPv4 or IPv6 addresses, respectively."; 614 } 615 leaf local-port { 616 if-feature "local-binding-supported"; 617 type inet:port-number; 618 default "0"; 619 description 620 "The local IP port number to bind to for when connecting 621 to the remote peer. The port number '0', which is the 622 default value, indicates that any available local port 623 number may be used."; 624 } 626 container proxy-server { 627 if-feature "proxy-connect"; 628 presence 629 "Indicates that a proxy connection is configured. 630 Present so that the 'proxy-type' node's 'mandatory 631 true' doesn't imply that the proxy connection 632 must be configured."; 633 choice proxy-type { 634 mandatory true; 635 description 636 "Selects a proxy connection protocol."; 637 case socks4 { 638 container socks4-parameters { 639 leaf remote-address { 640 type inet:ip-address; 641 mandatory true; 642 description 643 "The IP address of the proxy server."; 644 } 645 leaf remote-port { 646 type inet:port-number; 647 default "1080"; 648 description 649 "The IP port number for the proxy server."; 650 } 651 description 652 "Parameters for connecting to a TCP-based proxy 653 server using the SOCKS4 protocol."; 654 reference 655 "SOCKS, Proceedings: 1992 Usenix Security Symposium."; 656 } 657 } 658 case socks4a { 659 container socks4a-parameters { 660 leaf remote-address { 661 type inet:host; 662 mandatory true; 663 description 664 "The IP address or hostname of the proxy server."; 665 } 666 leaf remote-port { 667 type inet:port-number; 668 default "1080"; 669 description 670 "The IP port number for the proxy server."; 671 } 672 description 673 "Parameters for connecting to a TCP-based proxy 674 server using the SOCKS4a protocol."; 675 reference 676 "SOCKS Proceedings: 677 1992 Usenix Security Symposium. 678 OpenSSH message: 679 SOCKS 4A: A Simple Extension to SOCKS 4 Protocol 680 https://www.openssh.com/txt/socks4a.protocol"; 681 } 682 } 683 case socks5 { 684 container socks5-parameters { 685 leaf remote-address { 686 type inet:host; 687 mandatory true; 688 description 689 "The IP address or hostname of the proxy server."; 690 } 691 leaf remote-port { 692 type inet:port-number; 693 default "1080"; 694 description 695 "The IP port number for the proxy server."; 696 } 697 container authentication-parameters { 698 presence 699 "Indicates that an authentication mechanism 700 has been configured. Present so that the 701 'auth-type' node's 'mandatory true' doesn't 702 imply that an authentication mechanism 703 must be configured."; 704 description 705 "A container for SOCKS Version 5 authentication 706 mechanisms. 708 A complete list of methods is defined at: 709 https://www.iana.org/assignments/socks-methods 710 /socks-methods.xhtml."; 711 reference 712 "RFC 1928: SOCKS Protocol Version 5"; 713 choice auth-type { 714 mandatory true; 715 description 716 "A choice amongst supported SOCKS Version 5 717 authentication mechanisms."; 718 case gss-api { 719 if-feature socks5-gss-api; 720 container gss-api { 721 description 722 "Contains GSS-API configuration. Defines 723 as an empty container to enable specific 724 GSS-API configuration to be augmented in 725 by future modules."; 726 reference 727 "RFC 1928: SOCKS Protocol Version 5 728 RFC 2743: Generic Security Service 729 Application Program Interface 730 Version 2, Update 1"; 731 } 732 } 733 case username-password { 734 if-feature socks5-username-password; 735 container username-password { 736 leaf username { 737 type string; 738 description 739 "The 'username' value to use."; 740 } 741 leaf password { 742 type string; 743 description 744 "The 'password' value to use."; 745 } 746 description 747 "Contains Username/Password configuration."; 748 reference 749 "RFC 1929: Username/Password Authentication 750 for SOCKS V5"; 751 } 752 } 753 } 754 } 755 description 756 "Parameters for connecting to a TCP-based proxy server 757 using the SOCKS5 protocol."; 758 reference 759 "RFC 1928: SOCKS Protocol Version 5"; 760 } 761 } 762 } 763 description 764 "Proxy server settings."; 765 } 767 uses tcpcmn:tcp-connection-grouping { 768 augment "keepalives" { 769 if-feature "tcp-client-keepalives"; 770 description 771 "Add an if-feature statement so that implementations 772 can choose to support TCP client keepalives."; 773 } 774 } 775 } 776 } 778 780 5. The TCP Server Model 782 5.1. Tree Diagram 784 This section provides a tree diagram [RFC8340] for the "ietf-tcp- 785 server" module. 787 module: ietf-tcp-server 789 grouping tcp-server-grouping 790 +-- local-address inet:ip-address 791 +-- local-port? inet:port-number 792 +-- keepalives! {keepalives-supported}? 793 +-- idle-time uint16 794 +-- max-probes uint16 795 +-- probe-interval uint16 797 5.2. Example Usage 799 This section presents an example showing the "tcp-server-grouping" 800 populated with some data. 802 803 10.20.30.40 804 7777 805 806 15 807 3 808 30 809 810 812 5.3. YANG Module 814 The ietf-tcp-server YANG module references [RFC6991]. 816 file "ietf-tcp-server@2020-06-16.yang" 818 module ietf-tcp-server { 819 yang-version 1.1; 820 namespace "urn:ietf:params:xml:ns:yang:ietf-tcp-server"; 821 prefix tcps; 823 import ietf-inet-types { 824 prefix inet; 825 reference 826 "RFC 6991: Common YANG Data Types"; 827 } 828 import ietf-tcp-common { 829 prefix tcpcmn; 830 reference 831 "RFC DDDD: YANG Groupings for TCP Clients and TCP Servers"; 832 } 834 organization 835 "IETF NETCONF (Network Configuration) Working Group and the 836 IETF TCP Maintenance and Minor Extensions (TCPM) Working Group"; 838 contact 839 "WG Web: 840 841 WG List: 842 843 Authors: Kent Watsen 844 Michael Scharf 845 "; 847 description 848 "This module defines reusable groupings for TCP servers that 849 can be used as a basis for specific TCP server instances. 851 Copyright (c) 2020 IETF Trust and the persons identified 852 as authors of the code. All rights reserved. 854 Redistribution and use in source and binary forms, with 855 or without modification, is permitted pursuant to, and 856 subject to the license terms contained in, the Simplified 857 BSD License set forth in Section 4.c of the IETF Trust's 858 Legal Provisions Relating to IETF Documents 859 (https://trustee.ietf.org/license-info). 861 This version of this YANG module is part of RFC DDDD 862 (https://www.rfc-editor.org/info/rfcDDDD); see the RFC 863 itself for full legal notices. 865 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 866 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 867 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 868 are to be interpreted as described in BCP 14 (RFC 2119) 869 (RFC 8174) when, and only when, they appear in all 870 capitals, as shown here."; 872 revision 2020-06-16 { 873 description 874 "Initial version"; 875 reference 876 "RFC DDDD: YANG Groupings for TCP Clients and TCP Servers"; 877 } 879 // Features 881 feature tcp-server-keepalives { 882 description 883 "Per socket TCP keepalive parameters are configurable for 884 TCP servers on the server implementing this feature."; 885 } 887 // Groupings 889 grouping tcp-server-grouping { 890 description 891 "A reusable grouping for configuring a TCP server. 893 Note that this grouping uses fairly typical descendent 894 node names such that a stack of 'uses' statements will 895 have name conflicts. It is intended that the consuming 896 data model will resolve the issue (e.g., by wrapping 897 the 'uses' statement in a container called 898 'tcp-server-parameters'). This model purposely does 899 not do this itself so as to provide maximum flexibility 900 to consuming models."; 901 leaf local-address { 902 type inet:ip-address; 903 mandatory true; 904 description 905 "The local IP address to listen on for incoming 906 TCP client connections. INADDR_ANY (0.0.0.0) or 907 INADDR6_ANY (0:0:0:0:0:0:0:0 a.k.a. ::) MUST be 908 used when the server is to listen on all IPv4 or 909 IPv6 addresses, respectively."; 910 } 911 leaf local-port { 912 type inet:port-number; 913 default "0"; 914 description 915 "The local port number to listen on for incoming TCP 916 client connections. An invalid default value (0) 917 is used (instead of 'mandatory true') so that an 918 application level data model may 'refine' it with 919 an application specific default port number value."; 920 } 921 uses tcpcmn:tcp-connection-grouping { 922 augment "keepalives" { 923 if-feature "tcp-server-keepalives"; 924 description 925 "Add an if-feature statement so that implementations 926 can choose to support TCP server keepalives."; 927 } 928 } 929 } 930 } 932 934 6. Security Considerations 936 The YANG modules defined in this document are designed to be accessed 937 via YANG based management protocols, such as NETCONF [RFC6241] and 938 RESTCONF [RFC8040]. Both of these protocols have mandatory-to- 939 implement secure transport layers (e.g., SSH, TCP) with mutual 940 authentication. 942 The NETCONF access control model (NACM) [RFC8341] provides the means 943 to restrict access for particular users to a pre-configured subset of 944 all available protocol operations and content. 946 Since the modules defined in this document only define groupings, 947 these considerations are primarily for the designers of other modules 948 that use these groupings. 950 There are a number of data nodes defined in the YANG modules that are 951 writable/creatable/deletable (i.e., config true, which is the 952 default). These data nodes may be considered sensitive or vulnerable 953 in some network environments. Write operations (e.g., edit-config) 954 to these data nodes without proper protection can have a negative 955 effect on network operations. These are the subtrees and data nodes 956 and their sensitivity/vulnerability: 958 None of the writable/creatable/deletable data nodes in 959 the YANG modules defined in this document are considered more 960 sensitive or vulnerable then standard configuration. 962 Some of the readable data nodes in the YANG modules may be considered 963 sensitive or vulnerable in some network environments. It is thus 964 important to control read access (e.g., via get, get-config, or 965 notification) to these data nodes. These are the subtrees and data 966 nodes and their sensitivity/vulnerability: 968 None of the readable data nodes in the YANG modules 969 defined in this document are considered more sensitive or vulnerable 970 then standard configuration. 972 This document does not define any RPC actions and hence this section 973 does not consider the security of RPCs. 975 7. IANA Considerations 977 7.1. The IETF XML Registry 979 This document registers two URIs in the "ns" subregistry of the IETF 980 XML Registry [RFC3688]. Following the format in [RFC3688], the 981 following registrations are requested: 983 URI: urn:ietf:params:xml:ns:yang:ietf-tcp-client 984 Registrant Contact: The NETCONF WG of the IETF. 985 XML: N/A, the requested URI is an XML namespace. 987 URI: urn:ietf:params:xml:ns:yang:ietf-tcp-server 988 Registrant Contact: The NETCONF WG of the IETF. 989 XML: N/A, the requested URI is an XML namespace. 991 7.2. The YANG Module Names Registry 993 This document registers two YANG modules in the YANG Module Names 994 registry [RFC6020]. Following the format in [RFC6020], the following 995 registrations are requested: 997 name: ietf-tcp-common 998 namespace: urn:ietf:params:xml:ns:yang:ietf-tcp-common 999 prefix: tcpcmn 1000 reference: RFC DDDD 1002 name: ietf-tcp-client 1003 namespace: urn:ietf:params:xml:ns:yang:ietf-tcp-client 1004 prefix: tcpc 1005 reference: RFC DDDD 1007 name: ietf-tcp-server 1008 namespace: urn:ietf:params:xml:ns:yang:ietf-tcp-server 1009 prefix: tcps 1010 reference: RFC DDDD 1012 8. References 1014 8.1. Normative References 1016 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1017 Requirement Levels", BCP 14, RFC 2119, 1018 DOI 10.17487/RFC2119, March 1997, 1019 . 1021 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1022 the Network Configuration Protocol (NETCONF)", RFC 6020, 1023 DOI 10.17487/RFC6020, October 2010, 1024 . 1026 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 1027 RFC 6991, DOI 10.17487/RFC6991, July 2013, 1028 . 1030 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1031 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1032 . 1034 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1035 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1036 May 2017, . 1038 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 1039 Access Control Model", STD 91, RFC 8341, 1040 DOI 10.17487/RFC8341, March 2018, 1041 . 1043 8.2. Informative References 1045 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1046 DOI 10.17487/RFC3688, January 2004, 1047 . 1049 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1050 and A. Bierman, Ed., "Network Configuration Protocol 1051 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1052 . 1054 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1055 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1056 . 1058 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1059 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1060 . 1062 8.3. URIs 1064 [1] https://tools.ietf.org/html/draft-ietf-netconf-crypto-types 1066 [2] https://tools.ietf.org/html/draft-ietf-netconf-trust-anchors 1068 [3] https://tools.ietf.org/html/draft-ietf-netconf-keystore 1070 [4] https://tools.ietf.org/html/draft-ietf-netconf-tcp-client-server 1072 [5] https://tools.ietf.org/html/draft-ietf-netconf-ssh-client-server 1074 [6] https://tools.ietf.org/html/draft-ietf-netconf-tls-client-server 1076 [7] https://tools.ietf.org/html/draft-ietf-netconf-http-client-server 1078 [8] https://tools.ietf.org/html/draft-ietf-netconf-netconf-client- 1079 server 1081 [9] https://tools.ietf.org/html/draft-ietf-netconf-restconf-client- 1082 server 1084 Appendix A. Change Log 1086 A.1. 00 to 01 1088 o Added 'local-binding-supported' feature to TCP-client model. 1090 o Added 'keepalives-supported' feature to TCP-common model. 1092 o Added 'external-endpoint-values' container and 'external- 1093 endpoints' feature to TCP-server model. 1095 A.2. 01 to 02 1097 o Removed the 'external-endpoint-values' container and 'external- 1098 endpoints' feature from the TCP-server model. 1100 A.3. 02 to 03 1102 o Moved the common model section to be before the client and server 1103 specific sections. 1105 o Added sections "Model Scope" and "Usage Guidelines for Configuring 1106 TCP Keep-Alives" to the common model section. 1108 A.4. 03 to 04 1110 o Fixed a few typos. 1112 A.5. 04 to 05 1114 o Removed commented out "grouping tcp-system-grouping" statement 1115 kept for reviewers. 1117 o Added a "Note to Reviewers" note to first page. 1119 A.6. 05 to 06 1121 o Added support for TCP proxies. 1123 Authors' Addresses 1125 Kent Watsen 1126 Watsen Networks 1128 EMail: kent+ietf@watsen.net 1129 Michael Scharf 1130 Hochschule Esslingen - University of Applied Sciences 1132 EMail: michael.scharf@hs-esslingen.de