YANG Groupings for TCP Clients and TCP Servers
Extracted elements (25)
All three YANG modules define only 'grouping' statements with no protocol-accessible nodes of their own. This maximizes reusability: the groupings are instantiated by importing modules (e.g., SSH, TLS, HTTP, NETCONF, RESTCONF client/server models), which themselves provide the actual protocol-accessible nodes.
The document focuses on a minimum set of required TCP parameters—address/port binding, keepalives, and proxy traversal—rather than exposing the full TCP socket API. This intentionally narrow scope allows the groupings to serve as a stable foundation for higher-level protocol modules without overfitting to any single application.
The 'keepalives' node is modeled as a YANG 'presence' container rather than a plain container so that its mandatory descendant nodes do not imply that keepalives must always be configured, aligning with RFC 9293's requirement that keepalives default to off.
The 'proxy-server' node is a 'presence' container so that the mandatory 'proxy-type' choice descendant does not imply that a proxy-server must always be configured on implementations that enable the 'proxy-connect' feature.
The 'tcp-client-grouping' and 'tcp-server-grouping' groupings intentionally avoid wrapping their nodes in a named container (e.g., 'tcp-client-parameters') to provide maximum flexibility to consuming models, even though this creates potential for name conflicts when stacking 'uses' statements.
The YANG modules are NMDA-compliant (RFC 8342) and define no 'config false' (state) nodes. All data nodes are configuration nodes, which simplifies integration with NMDA-aware datastores (candidate, running, intended, operational).
This document is part of a layered YANG module collection. 'ietf-tcp-common', 'ietf-tcp-client', and 'ietf-tcp-server' sit at the base of a dependency chain that feeds into SSH client/server (RFC 9644), TLS client/server (RFC 9645), HTTP client/server, and ultimately NETCONF and RESTCONF client/server models.
A keepalive implementation MUST NOT interpret failure to respond to any specific keepalive probe as a dead connection, because ACK segments containing no data are not reliably transmitted by TCP.
A TCP keepalive mechanism SHOULD only be invoked in server applications that might otherwise hang indefinitely and consume resources unnecessarily if a client crashes or aborts a connection during a network failure.
If keepalives are needed by an application, it is RECOMMENDED that the liveness check happens only at the protocol layers that are meaningful to the application, given that keepalive mechanisms exist at multiple protocol layers.
Per RFC 9293, if keepalives are included in a TCP implementation, the application MUST be able to turn them on or off for each TCP connection, and keepalives MUST default to off. The 'keepalives' presence container in the YANG model aligns to this requirement.
The keepalive idle-time SHOULD NOT be smaller than 15 seconds; longer idle intervals SHOULD be used when possible. The default is 7200 seconds (two hours) per RFC 9293.
The keepalive probe-interval MUST NOT be smaller than one second to avoid congestion. Significantly longer intervals SHOULD be used to prevent harm on congested links from backing-off-less retransmissions.
When a hostname is configured as 'remote-address', DNS resolution should happen on each connection attempt; if multiple IP addresses result, they are tried in local preference order until a connection is established or all have failed.
YANG modules using 'tcp-client-grouping' or 'tcp-server-grouping' SHOULD refine the 'remote-port' or 'local-port' leaf with a 'default' statement when the port number is well-known, or with a 'mandatory' statement if a port number must always be configured.
The 'ietf-tcp-client' module defines features: 'local-binding-supported' (configurable local address/port), 'tcp-client-keepalives' (keepalives configurable for clients), 'proxy-connect' (proxy support), 'socks4-supported', 'socks4a-supported', 'socks5-supported' (requires proxy-connect), 'socks5-gss-api', and 'socks5-username-password' (each requiring socks5-supported).
The 'ietf-tcp-client' module defines the 'tcp-client-grouping' grouping with mandatory 'remote-address' (inet:host), optional 'remote-port' (inet:port-number), optional 'local-address' and 'local-port' (feature-gated by 'local-binding-supported'), an optional 'proxy-server' presence container (feature-gated by 'proxy-connect'), and uses tcp-common-grouping for keepalive parameters.
The 'ietf-tcp-common' module defines a single reusable grouping 'tcp-common-grouping' containing a presence container 'keepalives' with three leaves: 'idle-time' (uint16, seconds, default 7200), 'max-probes' (uint16, default 9), and 'probe-interval' (uint16, seconds, default 75). This grouping is shared by both the tcp-client and tcp-server modules.
The 'ietf-tcp-server' module defines the 'tcp-server-grouping' grouping with a 'local-bind' list (keyed on 'local-address', min-elements 1) containing 'local-address' (inet:ip-address, mandatory) and optional 'local-port' (inet:port-number), plus uses tcp-common-grouping for keepalive parameters.
The proxy-server container in 'tcp-client-grouping' supports three proxy types via a mandatory choice statement: socks4 (IP address only, default port 1080), socks4a (hostname or IP address, default port 1080), and socks5 (hostname or IP address, with optional authentication via GSS-API or username/password). Each type is gated by a corresponding YANG feature.
IANA has registered three modules in the 'YANG Module Names' registry (RFC 6020): 'ietf-tcp-common' (prefix tcpcmn), 'ietf-tcp-client' (prefix tcpc), and 'ietf-tcp-server' (prefix tcps), all referencing RFC 9643.
IANA has registered three URIs in the 'ns' registry of the IETF XML Registry (RFC 3688): 'urn:ietf:params:xml:ns:yang:ietf-tcp-common', 'urn:ietf:params:xml:ns:yang:ietf-tcp-client', and 'urn:ietf:params:xml:ns:yang:ietf-tcp-server'.
Implementations are RECOMMENDED to implement the 'local-binding-supported' feature for cryptographically secure protocols to enable more granular ingress/egress firewall rule bases. It is NOT RECOMMENDED to implement this feature for insecure protocols, per RFC 6056.
The SOCKS5 username/password node ('proxy-server/socks5-parameters/authentication-parameters/username-password/password') is sensitive to read operations and the NACM 'default-deny-all' extension has been applied to it. Configuration of cleartext passwords is NOT RECOMMENDED; the 'password-grouping' from RFC 9640 supports both cleartext and encrypted forms.
The YANG modules are designed to be accessed via YANG-based management protocols (NETCONF, RESTCONF), both of which have mandatory-to-implement secure transport layers (SSH, TLS, QUIC) and mandatory-to-implement mutual authentication. NACM (RFC 8341) provides access control for the managed nodes.