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