idnits 2.17.1
draft-kwatsen-netconf-tcp-client-server-00.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 :
----------------------------------------------------------------------------
No issues found here.
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
== Line 113 has weird spacing: '...address ine...'
== Line 122 has weird spacing: '...address ine...'
== Line 241 has weird spacing: '...te peer to co...'
== Line 334 has weird spacing: '...address ine...'
-- The document date (March 9, 2019) is 1867 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)
No issues found here.
Summary: 0 errors (**), 0 flaws (~~), 5 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 March 9, 2019
5 Expires: September 10, 2019
7 YANG Groupings for TCP Clients and TCP Servers
8 draft-kwatsen-netconf-tcp-client-server-00
10 Abstract
12 This document defines two YANG modules: the first defines a grouping
13 for configuring a generic TCP client, and the second defines a
14 grouping for configuring a generic TCP server. It is intended that
15 these groupings will be used by applications using the TCP protocol.
17 Editorial Note (To be removed by RFC Editor)
19 This draft contains many placeholder values that need to be replaced
20 with finalized values at the time of publication. This note
21 summarizes all of the substitutions that are needed. No other RFC
22 Editor instructions are specified elsewhere in this document.
24 Artwork in this document contains placeholder values for the date of
25 publication of this draft. Please apply the following replacement:
27 o "2019-03-09" --> the publication date of this draft
29 The following Appendix section is to be removed prior to publication:
31 o Appendix A. Change Log
33 Status of This Memo
35 This Internet-Draft is submitted in full conformance with the
36 provisions of BCP 78 and BCP 79.
38 Internet-Drafts are working documents of the Internet Engineering
39 Task Force (IETF). Note that other groups may also distribute
40 working documents as Internet-Drafts. The list of current Internet-
41 Drafts is at https://datatracker.ietf.org/drafts/current/.
43 Internet-Drafts are draft documents valid for a maximum of six months
44 and may be updated, replaced, or obsoleted by other documents at any
45 time. It is inappropriate to use Internet-Drafts as reference
46 material or to cite them other than as "work in progress."
48 This Internet-Draft will expire on September 10, 2019.
50 Copyright Notice
52 Copyright (c) 2019 IETF Trust and the persons identified as the
53 document authors. All rights reserved.
55 This document is subject to BCP 78 and the IETF Trust's Legal
56 Provisions Relating to IETF Documents
57 (https://trustee.ietf.org/license-info) in effect on the date of
58 publication of this document. Please review these documents
59 carefully, as they describe your rights and restrictions with respect
60 to this document. Code Components extracted from this document must
61 include Simplified BSD License text as described in Section 4.e of
62 the Trust Legal Provisions and are provided without warranty as
63 described in the Simplified BSD License.
65 Table of Contents
67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
68 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
69 3. The TCP Client Model . . . . . . . . . . . . . . . . . . . . 3
70 3.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 3
71 3.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 3
72 3.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 4
73 4. The TCP Server Model . . . . . . . . . . . . . . . . . . . . 7
74 4.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 7
75 4.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 8
76 4.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 8
77 5. Security Considerations . . . . . . . . . . . . . . . . . . . 11
78 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12
79 6.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 12
80 6.2. The YANG Module Names Registry . . . . . . . . . . . . . 13
81 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 13
82 7.1. Normative References . . . . . . . . . . . . . . . . . . 13
83 7.2. Informative References . . . . . . . . . . . . . . . . . 14
84 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 14
86 1. Introduction
88 This document defines two YANG 1.1 [RFC7950] modules: the first
89 defines a grouping for configuring a generic TCP client, and the
90 second defines a grouping for configuring a generic TCP server. It
91 is intended that these groupings will be used by applications using
92 the TCP protocol. For instance, these groupings could help define
93 the configuration module for an SSH, TLS, or HTTP based application.
95 2. Terminology
97 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
98 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
99 "OPTIONAL" in this document are to be interpreted as described in BCP
100 14 [RFC2119] [RFC8174] when, and only when, they appear in all
101 capitals, as shown here.
103 3. The TCP Client Model
105 3.1. Tree Diagram
107 This section provides a tree diagram [RFC8340] for the "ietf-tcp-
108 client" module.
110 module: ietf-tcp-client
112 grouping tcp-client-grouping
113 +-- remote-address inet:host
114 +-- remote-port? inet:port-number
115 +-- local-address? inet:ip-address
116 +-- local-port? inet:port-number
117 +-- tcp-keepalives {tcp-client-keepalives}?
118 +-- idle-time? uint16
119 +-- max-probes? uint16
120 +-- probe-interval? uint16
121 grouping ip-params-grouping
122 +-- remote-address inet:host
123 +-- remote-port? inet:port-number
124 +-- local-address? inet:ip-address
125 +-- local-port? inet:port-number
126 grouping keepalives-grouping
127 +-- tcp-keepalives {tcp-client-keepalives}?
128 +-- idle-time? uint16
129 +-- max-probes? uint16
130 +-- probe-interval? uint16
132 3.2. Example Usage
134 This section presents an example showing the tcp-client-grouping
135 populated with some data.
137
138 www.example.com
139 443
140 0.0.0.0
141 0
142
143 15
144 3
145 30
146
147
149 3.3. YANG Module
151 This YANG module has normative references to [RFC6991].
153 file "ietf-tcp-client@2019-03-09.yang"
154 module ietf-tcp-client {
155 yang-version 1.1;
156 namespace "urn:ietf:params:xml:ns:yang:ietf-tcp-client";
157 prefix tcpc;
159 import ietf-inet-types {
160 prefix inet;
161 reference
162 "RFC 6991: Common YANG Data Types";
163 }
165 organization
166 "IETF NETCONF (Network Configuration) Working Group";
168 contact
169 "WG Web:
170 WG List:
171 Author: Kent Watsen ";
173 description
174 "This module defines reusable groupings for TCP clients that
175 can be used as a basis for specific TCP client instances.
177 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL',
178 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED',
179 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document
180 are to be interpreted as described in BCP 14 [RFC2119]
181 [RFC8174] when, and only when, they appear in all
182 capitals, as shown here.
184 Copyright (c) 2019 IETF Trust and the persons identified as
185 authors of the code. All rights reserved.
187 Redistribution and use in source and binary forms, with or
188 without modification, is permitted pursuant to, and subject
189 to the license terms contained in, the Simplified BSD
190 License set forth in Section 4.c of the IETF Trust's
191 Legal Provisions Relating to IETF Documents
192 (http://trustee.ietf.org/license-info).
194 This version of this YANG module is part of RFC XXXX; see
195 the RFC itself for full legal notices.";
197 revision 2019-03-09 {
198 description
199 "Initial version";
200 reference
201 "RFC XXXX: YANG Groupings for TCP Clients and TCP Servers";
202 }
204 // Features
206 feature tcp-client-keepalives {
207 description
208 "Per socket TCP keepalive parameters are configurable for
209 TCP clients on the server implementing this feature.";
210 }
212 // Groupings
214 grouping tcp-client-grouping {
215 description
216 "A reusable grouping for configuring a TCP client.";
217 uses ip-params-grouping;
218 uses keepalives-grouping;
219 }
221 grouping ip-params-grouping {
222 description
223 "A reusable grouping for configuring TCP client IP level
224 parameters.";
225 leaf remote-address {
226 type inet:host;
227 mandatory true;
228 description
229 "The IP address or hostname of the remote peer to connect to.
230 If a domain name is configured, then the DNS resolution
231 should happen on each connection attempt. If the the DNS
232 resolution results in multiple IP addresses, the IP addresses
233 are tried according to local preference order until a
234 connection has been established or until all IP addresses
235 have failed.";
236 }
237 leaf remote-port {
238 type inet:port-number;
239 default "0";
240 description
241 "The IP port number for the remote peer to connect to. An
242 invalid default value (0) is used (instead of 'mandatory
243 true') so that a application level data model may 'refine'
244 it with an application specific default port number value.";
245 }
246 leaf local-address {
247 type inet:ip-address;
248 description
249 "The local IP address/interface (VRF?) to bind to for when
250 connecting to the remote peer. INADDR_ANY ('0.0.0.0') or
251 INADDR6_ANY ('0:0:0:0:0:0:0:0' a.k.a. '::') MAY be used to
252 explicitly indicate the implicit default, that the server
253 can bind to any IPv4 or IPv6 addresses, respectively.";
254 }
255 leaf local-port {
256 type inet:port-number;
257 default "0";
258 description
259 "The local IP port number to bind to for when connecting to
260 the remote peer. The port number '0', which is the default
261 value, indicates that any available local port number may
262 be used.";
263 }
264 }
266 grouping keepalives-grouping {
267 description
268 "A reusable grouping for configuring TCP client keepalive
269 parameters.";
270 container tcp-keepalives {
271 if-feature "tcp-client-keepalives";
272 description
273 "Configures the keep-alive policy, to proactively test the
274 aliveness of the TCP server. Not all clients will use
275 all the values, based on capabilities of the underlying
276 operating system. An unresponsive TCP server is dropped
277 after approximately (idle-time * 60) + (max-probes *
278 probe-interval) seconds.";
279 leaf idle-time {
280 type uint16 {
281 range "1..max";
282 }
283 units "minutes";
284 description
285 "Sets the amount of time in minutes after which if no data
286 has been received from the TCP server, a TCP-level probe
287 message will be sent to test the aliveness of the TCP
288 server. When 'idle-time' is not configured (the default)
289 TCP keep-alives are disabled.";
290 }
291 leaf max-probes {
292 type uint16 {
293 range "1..max";
294 }
295 description
296 "Sets the maximum number of sequential keep-alive probes
297 that can fail to obtain a response from the TCP server
298 before assuming the TCP server is no longer alive. If
299 no value is specified, then the operating system provided
300 default value is used.";
301 }
302 leaf probe-interval {
303 type uint16 {
304 range "1..max";
305 }
306 units "seconds";
307 description
308 "Sets the time interval between failed probes. If no value
309 is specified, then the operating system provided default
310 value is used.";
311 }
312 }
313 }
314 }
315
317 4. The TCP Server Model
319 4.1. Tree Diagram
321 This section provides a tree diagram [RFC8340] for the "ietf-tcp-
322 server" module.
324 module: ietf-tcp-server
326 grouping tcp-server-grouping
327 +-- local-address inet:ip-address
328 +-- local-port? inet:port-number
329 +-- tcp-keepalives {tcp-server-keepalives}?
330 +-- idle-time? uint16
331 +-- max-probes? uint16
332 +-- probe-interval? uint16
333 grouping ip-params-grouping
334 +-- local-address inet:ip-address
335 +-- local-port? inet:port-number
336 grouping keepalives-grouping
337 +-- tcp-keepalives {tcp-server-keepalives}?
338 +-- idle-time? uint16
339 +-- max-probes? uint16
340 +-- probe-interval? uint16
342 4.2. Example Usage
344 This section presents an example showing the tcp-server-grouping
345 populated with some data.
347
348 10.20.30.40
349 7777
350
351 15
352 3
353 30
354
355
357 4.3. YANG Module
359 This YANG module has normative references to [RFC6991].
361 file "ietf-tcp-server@2019-03-09.yang"
362 module ietf-tcp-server {
363 yang-version 1.1;
364 namespace "urn:ietf:params:xml:ns:yang:ietf-tcp-server";
365 prefix tcps;
367 import ietf-inet-types {
368 prefix inet;
369 reference
370 "RFC 6991: Common YANG Data Types";
371 }
372 organization
373 "IETF NETCONF (Network Configuration) Working Group";
375 contact
376 "WG Web:
377 WG List:
378 Author: Kent Watsen ";
380 description
381 "This module defines reusable groupings for TCP servers that
382 can be used as a basis for specific TCP server instances.
384 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL',
385 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED',
386 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document
387 are to be interpreted as described in BCP 14 [RFC2119]
388 [RFC8174] when, and only when, they appear in all
389 capitals, as shown here.
391 Copyright (c) 2019 IETF Trust and the persons identified as
392 authors of the code. All rights reserved.
394 Redistribution and use in source and binary forms, with or
395 without modification, is permitted pursuant to, and subject
396 to the license terms contained in, the Simplified BSD
397 License set forth in Section 4.c of the IETF Trust's
398 Legal Provisions Relating to IETF Documents
399 (http://trustee.ietf.org/license-info).
401 This version of this YANG module is part of RFC XXXX; see
402 the RFC itself for full legal notices.";
404 revision 2019-03-09 {
405 description
406 "Initial version";
407 reference
408 "RFC XXXX: YANG Groupings for TCP Clients and TCP Servers";
409 }
411 // Features
413 feature tcp-server-keepalives {
414 description
415 "Per socket TCP keepalive parameters are configurable for
416 TCP servers on the server implementing this feature.";
417 }
419 // Groupings
420 grouping tcp-server-grouping {
421 description
422 "A reusable grouping for configuring a TCP server.";
423 uses ip-params-grouping;
424 uses keepalives-grouping;
425 }
427 grouping ip-params-grouping {
428 description
429 "A reusable grouping for configuring TCP server IP level
430 parameters.";
431 leaf local-address {
432 type inet:ip-address;
433 mandatory true;
434 description
435 "The local IP address to listen on for incoming TCL
436 client connections. INADDR_ANY (0.0.0.0) or INADDR6_ANY
437 (0:0:0:0:0:0:0:0 a.k.a. ::) MUST be used when the server
438 is to listen on all IPv4 or IPv6 addresses, respectively.";
439 }
440 leaf local-port {
441 type inet:port-number;
442 default "0";
443 description
444 "The local port number to listen on for incoming TCP client
445 connections. An invalid default value (0) is used (instead
446 of 'mandatory true') so that a application level data model
447 may 'refine' it with an application specific default port
448 number value.";
449 }
450 }
452 grouping keepalives-grouping {
453 description
454 "A reusable grouping for configuring TCP server keepalive
455 parameters.";
456 container tcp-keepalives {
457 if-feature "tcp-server-keepalives";
458 description
459 "Configures the keep-alive policy, to proactively test the
460 aliveness of the TCP client. Not all servers will use
461 all the values, based on capabilities of the underlying
462 operating system. An unresponsive TCP client is dropped
463 after approximately (idle-time * 60) + (max-probes *
464 probe-interval) seconds.";
465 leaf idle-time {
466 type uint16 {
467 range "1..max";
469 }
470 units "minutes";
471 description
472 "Sets the amount of time in minutes after which if no data
473 has been received from the TCP client, a TCP-level probe
474 message will be sent to test the aliveness of the TCP
475 client. When 'idle-time' is not configured (the default)
476 TCP keep-alives are disabled.";
477 }
478 leaf max-probes {
479 type uint16 {
480 range "1..max";
481 }
482 description
483 "Sets the maximum number of sequential keep-alive probes
484 that can fail to obtain a response from the TCP client
485 before assuming the TCP client is no longer alive. If
486 no value is specified, then the operating system provided
487 default value is used.";
488 }
489 leaf probe-interval {
490 type uint16 {
491 range "1..max";
492 }
493 units "seconds";
494 description
495 "Sets the time interval between failed probes. If no value
496 is specified, then the operating system provided default
497 value is used.";
498 }
499 }
500 }
501 }
502
504 5. Security Considerations
506 The YANG modules defined in this document are designed to be accessed
507 via YANG based management protocols, such as NETCONF [RFC6241] and
508 RESTCONF [RFC8040]. Both of these protocols have mandatory-to-
509 implement secure transport layers (e.g., SSH, TCP) with mutual
510 authentication.
512 The NETCONF access control model (NACM) [RFC8341] provides the means
513 to restrict access for particular users to a pre-configured subset of
514 all available protocol operations and content.
516 Since the modules defined in this document only define groupings,
517 these considerations are primarily for the designers of other modules
518 that use these groupings.
520 There are a number of data nodes defined in the YANG modules that are
521 writable/creatable/deletable (i.e., config true, which is the
522 default). These data nodes may be considered sensitive or vulnerable
523 in some network environments. Write operations (e.g., edit-config)
524 to these data nodes without proper protection can have a negative
525 effect on network operations. These are the subtrees and data nodes
526 and their sensitivity/vulnerability:
528 NONE
530 Some of the readable data nodes in the YANG modules may be considered
531 sensitive or vulnerable in some network environments. It is thus
532 important to control read access (e.g., via get, get-config, or
533 notification) to these data nodes. These are the subtrees and data
534 nodes and their sensitivity/vulnerability:
536 NONE
538 Some of the RPC operations in this YANG module may be considered
539 sensitive or vulnerable in some network environments. It is thus
540 important to control access to these operations. These are the
541 operations and their sensitivity/vulnerability:
543 NONE
545 6. IANA Considerations
547 6.1. The IETF XML Registry
549 This document registers two URIs in the "ns" subregistry of the IETF
550 XML Registry [RFC3688]. Following the format in [RFC3688], the
551 following registrations are requested:
553 URI: urn:ietf:params:xml:ns:yang:ietf-tcp-client
554 Registrant Contact: The NETCONF WG of the IETF.
555 XML: N/A, the requested URI is an XML namespace.
557 URI: urn:ietf:params:xml:ns:yang:ietf-tcp-server
558 Registrant Contact: The NETCONF WG of the IETF.
559 XML: N/A, the requested URI is an XML namespace.
561 6.2. The YANG Module Names Registry
563 This document registers two YANG modules in the YANG Module Names
564 registry [RFC6020]. Following the format in [RFC6020], the following
565 registrations are requested:
567 name: ietf-tcp-client
568 namespace: urn:ietf:params:xml:ns:yang:ietf-tcp-client
569 prefix: tcpc
570 reference: RFC XXXX
572 name: ietf-tcp-server
573 namespace: urn:ietf:params:xml:ns:yang:ietf-tcp-server
574 prefix: tcps
575 reference: RFC XXXX
577 7. References
579 7.1. Normative References
581 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
582 Requirement Levels", BCP 14, RFC 2119,
583 DOI 10.17487/RFC2119, March 1997,
584 .
586 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
587 the Network Configuration Protocol (NETCONF)", RFC 6020,
588 DOI 10.17487/RFC6020, October 2010,
589 .
591 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types",
592 RFC 6991, DOI 10.17487/RFC6991, July 2013,
593 .
595 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
596 RFC 7950, DOI 10.17487/RFC7950, August 2016,
597 .
599 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
600 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
601 May 2017, .
603 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration
604 Access Control Model", STD 91, RFC 8341,
605 DOI 10.17487/RFC8341, March 2018,
606 .
608 7.2. Informative References
610 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
611 DOI 10.17487/RFC3688, January 2004,
612 .
614 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
615 and A. Bierman, Ed., "Network Configuration Protocol
616 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
617 .
619 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
620 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
621 .
623 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams",
624 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018,
625 .
627 Author's Address
629 Kent Watsen
630 Watsen Networks
632 EMail: kent+ietf@watsen.net