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