Network Working Group A. Huang Feng
Internet-Draft P. Francois
Intended status: Standards Track INSA-Lyon
Expires: 30 August 2025 K. Watsen
Watsen Networks
26 February 2025
YANG Groupings for UDP Clients and UDP Servers
draft-ietf-netconf-udp-client-server-06
Abstract
This document defines two YANG 1.1 modules with reusable groupings
for managing UDP clients and UDP servers.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on 30 August 2025.
Copyright Notice
Copyright (c) 2025 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. Code Components
extracted from this document must include Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License.
Huang Feng, et al. Expires 30 August 2025 [Page 1]
Internet-Draft udp-client-server-grouping February 2025
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Requirements Language . . . . . . . . . . . . . . . . . . 2
1.2. Adherence to the NMDA . . . . . . . . . . . . . . . . . . 2
1.3. Conventions . . . . . . . . . . . . . . . . . . . . . . . 3
2. The "ietf-udp-client" Module . . . . . . . . . . . . . . . . 3
2.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 3
2.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 4
2.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 4
3. The "ietf-udp-server" Module . . . . . . . . . . . . . . . . 7
3.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 7
3.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 8
3.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 8
4. Security Considerations . . . . . . . . . . . . . . . . . . . 10
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11
5.1. URI . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
5.2. YANG Module Name . . . . . . . . . . . . . . . . . . . . 11
6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 12
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 12
7.1. Normative References . . . . . . . . . . . . . . . . . . 12
7.2. Informative References . . . . . . . . . . . . . . . . . 13
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 14
1. Introduction
This document defines two YANG 1.1 [RFC7950] modules with reusable
groupings for managing UDP clients and UDP servers [RFC768]. These
modules may be used directly (e.g., define a specific UDP client or
UDP server) or in conjunction with the configuration defined for
higher level protocols that depend on UDP.
1.1. Requirements Language
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
1.2. Adherence to the NMDA
This document is compliant with the Network Management Datastore
Architecture (NMDA) [RFC8342]. It does not define any protocol
accessible nodes that are "config false".
Huang Feng, et al. Expires 30 August 2025 [Page 2]
Internet-Draft udp-client-server-grouping February 2025
1.3. Conventions
Various examples in this document use the XML [W3C.REC-xml-20081126]
encoding. Other encodings, such as JSON [RFC8259], could
alternatively be used.
2. The "ietf-udp-client" Module
This section defines a YANG 1.1 module called "ietf-udp-client".
This YANG module defines the "udp-client" grouping for providing UDP
clients with remote server information.
Section 2.1 provides the overview of the YANG module. An example of
usage is illustrated in Section 2.2, while Section 2.3 defines the
YANG module itself.
2.1. Data Model Overview
This section provides an overview of the features and the grouping
defined in the "ietf-udp-client" YANG module.
2.1.1. Features
The "ietf-udp-client" module defines the following "feature"
statement:
Features:
+-- local-binding
This feature indicates that the client supports configuring local
bindings (i.e., the local address and local port number) for UDP
clients.
The diagram above uses syntax that is similar to but not defined in
[RFC8340].
2.1.2. The "udp-client" Grouping
The following tree diagram [RFC8340] illustrates the tree structure
of the "udp-client" grouping:
module: ietf-udp-client
grouping udp-client:
+-- remote-address inet:host
+-- remote-port? inet:port-number
+-- local-address? inet:ip-address {local-binding}?
+-- local-port? inet:port-number {local-binding}?
Huang Feng, et al. Expires 30 August 2025 [Page 3]
Internet-Draft udp-client-server-grouping February 2025
The description of these parameters is provided below:
* The "remote-address", which is mandatory, may be configured as an
IPv4 address, an IPv6 address, or a hostname. The resolved
address should be compatible with the local address family, if
also provided.
* The "remote-port" is defined with neither a "default" nor a
"mandatory" statement. YANG modules using this grouping SHOULD
refine the grouping with a "default" statement, when the port
number is well-known (e.g., a port number allocated by IANA), or
with a "mandatory" statement, if a port number needs to always be
configured. This MAY be ignored when the port number is neither
well-known nor mandatory to configure, such as might be the case
when this grouping is used by another grouping.
* The "local-address", which is enabled by the "local-binding"
feature, may be configured as an IPv4 address, an IPv6 address, or
a wildcard value. The local address must use the same address
family as the configured remote address.
* The "local-port", which depends on the "local-binding" feature, is
not mandatory. Its default value is "0", indicating that the
operating system can select an arbitrary port number.
2.2. Example Usage
This section presents an example of usage of the "udp-client"
grouping.
<!-- The outermost element below doesn't exist in the data model. -->
<!-- It simulates if the "grouping" were a "container" instead. -->
<udp-client xmlns="urn:ietf:params:xml:ns:yang:ietf-udp-client">
<remote-address>www.example.com</remote-address>
<remote-port>10000</remote-port>
<local-address>192.0.2.2</local-address>
<local-port>12345</local-port>
</udp-client>
2.3. YANG Module
This module imports types defined in [RFC6991].
Huang Feng, et al. Expires 30 August 2025 [Page 4]
Internet-Draft udp-client-server-grouping February 2025
<CODE BEGINS> file "ietf-udp-client@2025-02-24.yang"
module ietf-udp-client {
yang-version 1.1;
namespace
"urn:ietf:params:xml:ns:yang:ietf-udp-client";
prefix udpc;
import ietf-inet-types {
prefix inet;
reference
"RFC 6991: Common YANG Data Types";
}
organization "IETF NETCONF (Network Configuration) Working Group";
contact
"WG Web: <http:/tools.ietf.org/wg/netconf/>
WG List: <mailto:netconf@ietf.org>
Authors: Alex Huang Feng
<mailto:alex.huang-feng@insa-lyon.fr>
Pierre Francois
<mailto:pierre.francois@insa-lyon.fr>";
description
"Defines a generic grouping for UDP-based client applications.
Copyright (c) 2025 IETF Trust and the persons identified as
authors of the code. All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, is permitted pursuant to, and subject to the license
terms contained in, the Revised BSD License set forth in Section
4.c of the IETF Trust's Legal Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC-to-be; see the RFC
itself for full legal notices.";
revision 2025-02-24 {
description
"Initial revision";
reference
"RFC-to-be: YANG Groupings for UDP Clients and UDP Servers";
}
feature local-binding {
description
"Indicates that the UDP client supports configuring local
bindings (i.e., the local address and local port number) for
Huang Feng, et al. Expires 30 August 2025 [Page 5]
Internet-Draft udp-client-server-grouping February 2025
UDP clients.";
}
grouping udp-client {
description
"A reusable grouping for UDP clients.
Note that this grouping uses fairly typical descendant
node names such that a stack of 'uses' statements will
have name conflicts. It is intended that the consuming
data model will resolve the issue (e.g., by wrapping
the 'uses' statement in a container called
'udp-client-parameters'). This model purposely does
not do this itself so as to provide maximum flexibility
to consuming models. An example is shown in section 5
of RFC6724.";
leaf remote-address {
type inet:host;
mandatory true;
description
"The IP address or hostname of the remote UDP server.
If a domain name is configured, then the name resolution should
happen on each connection attempt, unless a previously resolved
address is cached and still valid. If the name resolution
results in multiple IP addresses, the IP addresses
are tried until a connection has been established or
until all IP addresses have failed. ";
}
leaf remote-port {
type inet:port-number;
description
"The port number of the remote UDP server.";
}
leaf local-address {
if-feature "local-binding";
type inet:ip-address;
description
"The local IP address to bind to when sending UDP
messages to the remote server. INADDR_ANY ('0.0.0.0') or
INADDR6_ANY ('0:0:0:0:0:0:0:0' a.k.a. '::') may be used
so that the server can bind to any IPv4 or IPv6 address.";
}
leaf local-port {
if-feature "local-binding";
Huang Feng, et al. Expires 30 August 2025 [Page 6]
Internet-Draft udp-client-server-grouping February 2025
type inet:port-number;
default "0";
description
"The local port number to bind to when sending UDP
datagrams to the remote server. The port number '0',
which is the default value, indicates that any available
local port number may be used.";
}
}
}
<CODE ENDS>
3. The "ietf-udp-server" Module
This section defines a YANG 1.1 module called "ietf-udp-server".
This YANG module defines the "udp-server" grouping for configuring
UDP servers.
Section 3.1 provides an overview of the YANG module for configuring
UDP servers. An example of usage is illustrated in Section 3.2 while
Section 3.3 defines the YANG module itself.
3.1. Data Model Overview
This section provides an overview of the grouping defined in the
"ietf-udp-server" module.
3.1.1. The "udp-server" Grouping
The following tree diagram [RFC8340] illustrates the structure of
"udp-server" grouping:
module: ietf-udp-server
grouping udp-server:
+-- local-bind* [local-address]
+-- local-address inet:ip-address
+-- local-port? inet:port-number
The description of these parameters is provided below:
* The "local-address", which is mandatory, may be configured as an
IPv4 address, an IPv6 address, or a wildcard value.
* The "local-port" is defined with neither a "default" nor a
"mandatory" statement. YANG modules using this grouping SHOULD
refine the grouping with a "default" statement, when the port
number is well-known (e.g., a port number allocated by IANA), or
Huang Feng, et al. Expires 30 August 2025 [Page 7]
Internet-Draft udp-client-server-grouping February 2025
with a "mandatory" statement, if a port number needs to always be
configured. This MAY be ignored when the port number is neither
well-known nor mandatory to configure, such as might be the case
when this grouping is used by another grouping.
3.2. Example Usage
This section presents two examples of usage of the "udp-server"
grouping.
This following shows an example of a server configured for listening
to an IPv4 address:
<!-- The outermost element below doesn't exist in the data model. -->
<!-- It simulates if the "grouping" were a "container" instead. -->
<udp-server xmlns="urn:ietf:params:xml:ns:yang:ietf-udp-server">
<local-bind>
<local-address>192.0.2.2</local-address>
<local-port>49152</local-port>
</local-bind>
</udp-server>
This following shows an example of a server configured to listen to
an IPv4 and IPv6 together:
<!-- The outermost element below doesn't exist in the data model. -->
<!-- It simulates if the "grouping" were a "container" instead. -->
<udp-server xmlns="urn:ietf:params:xml:ns:yang:ietf-udp-server">
<local-bind>
<local-address>192.0.2.2</local-address>
<local-port>49152</local-port>
</local-bind>
<local-bind>
<local-address>2001:db8::0</local-address>
<local-port>49153</local-port>
</local-bind>
</udp-server>
3.3. YANG Module
The "ietf-udp-server" imports types defined in [RFC6991].
Huang Feng, et al. Expires 30 August 2025 [Page 8]
Internet-Draft udp-client-server-grouping February 2025
<CODE BEGINS> file "ietf-udp-server@2025-02-24.yang"
module ietf-udp-server {
yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-udp-server";
prefix udps;
import ietf-inet-types {
prefix inet;
reference
"RFC 6991: Common YANG Data Types";
}
organization
"IETF NETCONF (Network Configuration) Working Group";
contact
"WG Web: <http:/tools.ietf.org/wg/netconf/>
WG List: <mailto:netconf@ietf.org>
Authors: Alex Huang Feng
<mailto:alex.huang-feng@insa-lyon.fr>
Pierre Francois
<mailto:pierre.francois@insa-lyon.fr>";
description
"Defines a generic grouping for UDP-based server applications.
Copyright (c) 2025 IETF Trust and the persons identified as
authors of the code. All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, is permitted pursuant to, and subject to the license
terms contained in, the Revised BSD License set forth in Section
4.c of the IETF Trust's Legal Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC-to-be; see the RFC
itself for full legal notices.";
revision 2025-02-24 {
description
"Initial revision";
reference
"RFC-to-be: YANG Groupings for UDP Clients and UDP Servers";
}
grouping udp-server {
description
"Provides a reusable grouping for configuring UDP servers.
Huang Feng, et al. Expires 30 August 2025 [Page 9]
Internet-Draft udp-client-server-grouping February 2025
Note that this grouping uses fairly typical descendant
node names such that a stack of 'uses' statements will
have name conflicts. It is intended that the consuming
data model will resolve the issue (e.g., by wrapping
the 'uses' statement in a container called
'udp-server-parameters'). This model purposely does
not do this itself so as to provide maximum flexibility
to consuming models.";
list local-bind {
key "local-address";
min-elements 1;
description
"A list of bind (listen) points for this server
instance. A server instance may have multiple
bind points to support, e.g., the same port number in
different address families or different port numbers
in the same address family.";
leaf local-address {
type inet:ip-address;
mandatory true;
description
"The local IP address to listen on for incoming
UDP datagrams. To configure listening
on all IPv4 addresses the value must be '0.0.0.0'
(INADDR_ANY). To configure listening on all IPv6
addresses the value must be '::' (INADDR6_ANY).";
}
leaf local-port {
type inet:port-number;
description
"The local port number to listen on for incoming UDP
messages.";
}
}
}
}
<CODE ENDS>
4. Security Considerations
This section uses the template described in Section 3.7 of
[I-D.ietf-netmod-rfc8407bis].
Huang Feng, et al. Expires 30 August 2025 [Page 10]
Internet-Draft udp-client-server-grouping February 2025
The "ietf-udp-client" and "ietf-udp-server" YANG modules defines a
data model that is designed to be accessed via YANG-based management
protocols, such as NETCONF [RFC6241] and RESTCONF [RFC8040]. These
protocols have to use a secure transport layer (e.g., SSH [RFC6242],
TLS [RFC8446], and QUIC [RFC9000]) and have to use mutual
authentication.
The Network Configuration Access Control Model (NACM) [RFC8341]
provides the means to restrict access for particular NETCONF or
RESTCONF users to a preconfigured subset of all available NETCONF or
RESTCONF protocol operations and content.
The YANG modules define a set of identities, types, and groupings.
These nodes are intended to be reused by other YANG modules. The
module by itself does not expose any data nodes that are writable,
data nodes that contain read-only state, or RPCs. As such, there are
no additional security issues related to the YANG module that need to
be considered.
Modules that use the groupings that are defined in this document
should identify the corresponding security considerations. For
example, reusing some of these groupings will expose privacy-related
information (e.g., 'remote-address', 'remote-port', 'local-address'
or 'local-port').
5. IANA Considerations
This document describes the URIs from IETF XML Registry and the
registration of a two new YANG module names
5.1. URI
IANA is requested to assign two new URIs from the IETF XML Registry
[RFC3688]:
URI: urn:ietf:params:xml:ns:yang:ietf-udp-client
Registrant Contact: The IESG.
XML: N/A; the requested URI is an XML namespace.
URI: urn:ietf:params:xml:ns:yang:ietf-udp-server
Registrant Contact: The IESG.
XML: N/A; the requested URI is an XML namespace.
5.2. YANG Module Name
This document also requests IANA to register the following YANG
modules in the YANG Module Names registry [RFC6020] within the "YANG
Parameters" registry group:
Huang Feng, et al. Expires 30 August 2025 [Page 11]
Internet-Draft udp-client-server-grouping February 2025
name: ietf-udp-client
namespace: urn:ietf:params:xml:ns:yang:ietf-udp-client
prefix: udpc
maintained by IANA? N
reference: RFC-to-be
name: ietf-udp-server
namespace: urn:ietf:params:xml:ns:yang:ietf-udp-server
prefix: udps
maintained by IANA? N
reference: RFC-to-be
6. Acknowledgements
The authors would like to thank Mohamed Boucadair, Benoit Claise,
Qiufang Ma and Qin Wu for their review and valuable comments.
7. References
7.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
DOI 10.17487/RFC3688, January 2004,
<https://www.rfc-editor.org/info/rfc3688>.
[RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
the Network Configuration Protocol (NETCONF)", RFC 6020,
DOI 10.17487/RFC6020, October 2010,
<https://www.rfc-editor.org/info/rfc6020>.
[RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types",
RFC 6991, DOI 10.17487/RFC6991, July 2013,
<https://www.rfc-editor.org/info/rfc6991>.
[RFC768] Postel, J., "User Datagram Protocol", STD 6, RFC 768,
DOI 10.17487/RFC0768, August 1980,
<https://www.rfc-editor.org/info/rfc768>.
[RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
RFC 7950, DOI 10.17487/RFC7950, August 2016,
<https://www.rfc-editor.org/info/rfc7950>.
Huang Feng, et al. Expires 30 August 2025 [Page 12]
Internet-Draft udp-client-server-grouping February 2025
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams",
BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018,
<https://www.rfc-editor.org/info/rfc8340>.
[RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration
Access Control Model", STD 91, RFC 8341,
DOI 10.17487/RFC8341, March 2018,
<https://www.rfc-editor.org/info/rfc8341>.
7.2. Informative References
[I-D.ietf-netmod-rfc8407bis]
Bierman, A., Boucadair, M., and Q. Wu, "Guidelines for
Authors and Reviewers of Documents Containing YANG Data
Models", Work in Progress, Internet-Draft, draft-ietf-
netmod-rfc8407bis-22, 14 January 2025,
<https://datatracker.ietf.org/doc/html/draft-ietf-netmod-
rfc8407bis-22>.
[RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
and A. Bierman, Ed., "Network Configuration Protocol
(NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
<https://www.rfc-editor.org/info/rfc6241>.
[RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure
Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011,
<https://www.rfc-editor.org/info/rfc6242>.
[RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
<https://www.rfc-editor.org/info/rfc8040>.
[RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", STD 90, RFC 8259,
DOI 10.17487/RFC8259, December 2017,
<https://www.rfc-editor.org/info/rfc8259>.
[RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
and R. Wilton, "Network Management Datastore Architecture
(NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018,
<https://www.rfc-editor.org/info/rfc8342>.
Huang Feng, et al. Expires 30 August 2025 [Page 13]
Internet-Draft udp-client-server-grouping February 2025
[RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol
Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
<https://www.rfc-editor.org/info/rfc8446>.
[RFC9000] Iyengar, J., Ed. and M. Thomson, Ed., "QUIC: A UDP-Based
Multiplexed and Secure Transport", RFC 9000,
DOI 10.17487/RFC9000, May 2021,
<https://www.rfc-editor.org/info/rfc9000>.
[RFC9110] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "HTTP Semantics", STD 97, RFC 9110,
DOI 10.17487/RFC9110, June 2022,
<https://www.rfc-editor.org/info/rfc9110>.
[W3C.REC-xml-20081126]
Bray, T., Paoli, J., Sperberg-McQueen, C.M., Maler, E.,
and F. Yergeau, "Extensible Markup Language (XML) 1.0
(Fifth Edition)", World Wide Web Consortium
Recommendation REC-xml-20081126, November 2008,
<https://www.w3.org/TR/2008/REC-xml-20081126/>.
Authors' Addresses
Alex Huang Feng
INSA-Lyon
Lyon
France
Email: alex.huang-feng@insa-lyon.fr
Pierre Francois
INSA-Lyon
Lyon
France
Email: pierre.francois@insa-lyon.fr
Kent Watsen
Watsen Networks
Email: kent+ietf@watsen.net
Huang Feng, et al. Expires 30 August 2025 [Page 14]