rfc9643v2.txt		rfc9643.txt
	skipping to change at line 99 ¶		skipping to change at line 99 ¶
	conjunction with the configuration defined for higher level protocols		conjunction with the configuration defined for higher level protocols
	that depend on TCP (e.g., SSH, TLS, etc.). Examples of higher level		that depend on TCP (e.g., SSH, TLS, etc.). Examples of higher level
	protocol configuration designed to be used in conjunction with this		protocol configuration designed to be used in conjunction with this
	configuration are in [RFC9644] and [RFC9645].		configuration are in [RFC9644] and [RFC9645].
	The modules focus on three different types of base TCP parameters		The modules focus on three different types of base TCP parameters
	that matter for TCP-based applications: First, the modules cover		that matter for TCP-based applications: First, the modules cover
	fundamental configuration of a TCP client or TCP server application,		fundamental configuration of a TCP client or TCP server application,
	such as addresses and port numbers. Second, a reusable grouping		such as addresses and port numbers. Second, a reusable grouping
	enables modification of application-specific parameters for TCP		enables modification of application-specific parameters for TCP
	connections, such as use of TCP keep-alives. And third, client		connections, such as use of TCP keepalives. And third, client
	configuration for traversing proxies is included as well. In each		configuration for traversing proxies is included as well. In each
	case, the modules have a very narrow scope and focus on a minimum set		case, the modules have a very narrow scope and focus on a minimum set
	of required parameters.		of required parameters.
	Please be advised that while this document presents support for some		Please be advised that while this document presents support for some
	TCP proxy techniques, there are other TCP proxy techniques that are		TCP proxy techniques, there are other TCP proxy techniques that are
	not part of this document but could be added by augmenting the YANG		not part of this document but could be added by augmenting the YANG
	module.		module.
	1.1. Relation to Other RFCs		1.1. Relation to Other RFCs
	skipping to change at line 209 ¶		skipping to change at line 209 ¶
	terms of its features and groupings.		terms of its features and groupings.
	2.1.1. Model Scope		2.1.1. Model Scope
	This document presents a common "grouping" statement for basic TCP		This document presents a common "grouping" statement for basic TCP
	connection parameters that matter to applications. It is "common" in		connection parameters that matter to applications. It is "common" in
	that this grouping is used by both the "ietf-tcp-client" and "ietf-		that this grouping is used by both the "ietf-tcp-client" and "ietf-
	tcp-server" modules. In some TCP stacks, such parameters can also		tcp-server" modules. In some TCP stacks, such parameters can also
	directly be set by an application using system calls, such as the		directly be set by an application using system calls, such as the
	sockets API. The base YANG data model in this document focuses on		sockets API. The base YANG data model in this document focuses on
	modeling TCP keep-alives. This base model can be extended as needed.		modeling TCP keepalives. This base model can be extended as needed.
	2.1.2. Features		2.1.2. Features
	The following diagram lists all the "feature" statements defined in		The following diagram lists all the "feature" statements defined in
	the "ietf-tcp-common" module:		the "ietf-tcp-common" module:
	Features:		Features:
	+-- keepalives-supported		+-- keepalives-supported
	The diagram above uses syntax that is similar to but not defined in		The diagram above uses syntax that is similar to but not defined in
	skipping to change at line 245 ¶		skipping to change at line 245 ¶
	grouping tcp-common-grouping:		grouping tcp-common-grouping:
	+-- keepalives! {keepalives-supported}?		+-- keepalives! {keepalives-supported}?
	+-- idle-time? uint16		+-- idle-time? uint16
	+-- max-probes? uint16		+-- max-probes? uint16
	+-- probe-interval? uint16		+-- probe-interval? uint16
	Comments:		Comments:
	* The "keepalives" node is a "presence" container so that the		* The "keepalives" node is a "presence" container so that the
	mandatory descendant nodes do not imply that keep-alives must be		mandatory descendant nodes do not imply that keepalives must be
	configured.		configured.
	* The "idle-time", "max-probes", and "probe-interval" nodes have the		* The "idle-time", "max-probes", and "probe-interval" nodes have the
	common meanings. Please see the YANG module in Section 2.3 for		common meanings. Please see the YANG module in Section 2.3 for
	details.		details.
	2.1.4. Protocol-Accessible Nodes		2.1.4. Protocol-Accessible Nodes
	The "ietf-tcp-common" module defines only "grouping" statements that		The "ietf-tcp-common" module defines only "grouping" statements that
	are used by other modules to instantiate protocol-accessible nodes.		are used by other modules to instantiate protocol-accessible nodes.
	Thus, this module, when implemented, does not itself define any		Thus, this module, when implemented, does not itself define any
	protocol-accessible nodes.		protocol-accessible nodes.
	2.1.5. Guidelines for Configuring TCP Keep-Alives		2.1.5. Guidelines for Configuring TCP Keepalives
	Network stacks may include keep-alives in their TCP implementations,		Network stacks may include keepalives in their TCP implementations,
	although this practice is not universally implemented. If keep-		although this practice is not universally implemented. If keepalives
	alives are included, [RFC9293] mandates that the application MUST be		are included, [RFC9293] mandates that the application MUST be able to
	able to turn them on or off for each TCP connection and that they		turn them on or off for each TCP connection and that they MUST
	MUST default to off.		default to off.
	Keep-alive mechanisms exist in many protocols. Depending on the		Keepalive mechanisms exist in many protocols. Depending on the
	protocol stack, TCP keep-alives may only be one out of several		protocol stack, TCP keepalives may only be one out of several
	alternatives. Which mechanism(s) to use depends on the use case and		alternatives. Which mechanism(s) to use depends on the use case and
	application requirements. If keep-alives are needed by an		application requirements. If keepalives are needed by an
	application, it is RECOMMENDED that the liveness check happens only		application, it is RECOMMENDED that the liveness check happens only
	at the protocol layers that are meaningful to the application.		at the protocol layers that are meaningful to the application.
	A TCP keep-alive mechanism SHOULD only be invoked in server		A TCP keepalive mechanism SHOULD only be invoked in server
	applications that might otherwise hang indefinitely and consume		applications that might otherwise hang indefinitely and consume
	resources unnecessarily if a client crashes or aborts a connection		resources unnecessarily if a client crashes or aborts a connection
	during a network failure [RFC9293]. TCP keep-alives may consume		during a network failure [RFC9293]. TCP keepalives may consume
	significant resources both in the network and in endpoints (e.g.,		significant resources both in the network and in endpoints (e.g.,
	battery power). In addition, frequent keep-alives risk network		battery power). In addition, frequent keepalives risk network
	congestion. The higher the frequency of keep-alives, the higher the		congestion. The higher the frequency of keepalives, the higher the
	overhead.		overhead.
	Given the cost of keep-alives, parameters have to be configured		Given the cost of keepalives, parameters have to be configured
	carefully:		carefully:
	* The default idle interval (leaf "idle-time") is two hours, i.e.,		* The default idle interval (leaf "idle-time") is two hours, i.e.,
	7200 seconds [RFC9293]. A lower value MAY be configured, but idle		7200 seconds [RFC9293]. A lower value MAY be configured, but idle
	intervals SHOULD NOT be smaller than 15 seconds. Longer idle		intervals SHOULD NOT be smaller than 15 seconds. Longer idle
	intervals SHOULD be used when possible.		intervals SHOULD be used when possible.
	* The maximum number of sequential keep-alive probes that can fail		* The maximum number of sequential keepalive probes that can fail
	(leaf "max-probes") trades off responsiveness and robustness		(leaf "max-probes") trades off responsiveness and robustness
	against packet loss. ACK segments that contain no data are not		against packet loss. ACK segments that contain no data are not
	reliably transmitted by TCP. Consequently, if a keep-alive		reliably transmitted by TCP. Consequently, if a keepalive
	mechanism is implemented, it MUST NOT interpret failure to respond		mechanism is implemented, it MUST NOT interpret failure to respond
	to any specific probe as a dead connection [RFC9293]. Typically,		to any specific probe as a dead connection [RFC9293]. Typically,
	a single-digit number should suffice.		a single-digit number should suffice.
	* TCP implementations may include a parameter for the number of		* TCP implementations may include a parameter for the number of
	seconds between TCP keep-alive probes (leaf "probe-interval"). In		seconds between TCP keepalive probes (leaf "probe-interval"). In
	order to avoid congestion, the time interval between probes MUST		order to avoid congestion, the time interval between probes MUST
	NOT be smaller than one second. Significantly longer intervals		NOT be smaller than one second. Significantly longer intervals
	SHOULD be used. It is important to note that keep-alive probes		SHOULD be used. It is important to note that keepalive probes (or
	(or replies) can get dropped due to network congestion. Sending		replies) can get dropped due to network congestion. Sending
	further probe messages into a congested path after a short		further probe messages into a congested path after a short
	interval, without backing off timers, could cause harm and result		interval, without backing off timers, could cause harm and result
	in a congestion collapse. Therefore, it is essential to pick a		in a congestion collapse. Therefore, it is essential to pick a
	large, conservative value for this interval.		large, conservative value for this interval.
	2.2. Example Usage		2.2. Example Usage
	This section presents an example showing the "tcp-common-grouping"		This section presents an example showing the "tcp-common-grouping"
	grouping populated with some data.		grouping populated with some data.
			The following example uses the XML [W3C.REC-xml-20081126] encoding.
	<!-- The outermost element below doesn't exist in the data model. -->		<!-- The outermost element below doesn't exist in the data model. -->
	<!-- It simulates if the "grouping" were a "container" instead. -->		<!-- It simulates if the "grouping" were a "container" instead. -->
	<tcp-common xmlns="urn:ietf:params:xml:ns:yang:ietf-tcp-common">		<tcp-common xmlns="urn:ietf:params:xml:ns:yang:ietf-tcp-common">
	<keepalives>		<keepalives>
	<idle-time>7200</idle-time>		<idle-time>7200</idle-time>
	<max-probes>9</max-probes>		<max-probes>9</max-probes>
	<probe-interval>75</probe-interval>		<probe-interval>75</probe-interval>
	</keepalives>		</keepalives>
	</tcp-common>		</tcp-common>
	skipping to change at line 485 ¶		skipping to change at line 487 ¶
	+-- socks5-supported {proxy-connect}?		+-- socks5-supported {proxy-connect}?
	+-- socks5-gss-api {socks5-supported}?		+-- socks5-gss-api {socks5-supported}?
	+-- socks5-username-password {socks5-supported}?		+-- socks5-username-password {socks5-supported}?
	Comments:		Comments:
	* The "local-binding-supported" feature indicates that the server		* The "local-binding-supported" feature indicates that the server
	supports configuring local bindings (i.e., the local address and		supports configuring local bindings (i.e., the local address and
	local port) for TCP clients.		local port) for TCP clients.
	* The "tcp-client-keepalives" feature indicates that per socket TCP		* The "tcp-client-keepalives" feature indicates that TCP keepalive
	keepalive parameters are configurable for TCP clients on the		parameters are configurable for TCP clients on the server
	server implementing this feature.		implementing this feature.
	* The "proxy-connect" feature indicates the TCP client supports		* The "proxy-connect" feature indicates the TCP client supports
	connecting through TCP proxies.		connecting through TCP proxies.
	* The "socks4-supported" feature indicates the TCP client supports		* The "socks4-supported" feature indicates the TCP client supports
	Socks4-based proxies.		Socks4-based proxies.
	* The "socks4a-supported" feature indicates the TCP client supports		* The "socks4a-supported" feature indicates the TCP client supports
	Socks4a-based proxies. The difference between Socks4 and Socks4a		Socks4a-based proxies. The difference between Socks4 and Socks4a
	is that Socks4a enables the "remote-address" to be specified using		is that Socks4a enables the "remote-address" to be specified using
	skipping to change at line 608 ¶		skipping to change at line 610 ¶
	are used by other modules to instantiate protocol-accessible nodes.		are used by other modules to instantiate protocol-accessible nodes.
	Thus, this module, when implemented, does not itself define any		Thus, this module, when implemented, does not itself define any
	protocol-accessible nodes.		protocol-accessible nodes.
	3.2. Example Usage		3.2. Example Usage
	This section presents two examples showing the "tcp-client-grouping"		This section presents two examples showing the "tcp-client-grouping"
	grouping populated with some data. This example shows a TCP client		grouping populated with some data. This example shows a TCP client
	configured to not connect via a proxy:		configured to not connect via a proxy:
			The following example uses the XML [W3C.REC-xml-20081126] encoding.
	<!-- The outermost element below doesn't exist in the data model. -->		<!-- The outermost element below doesn't exist in the data model. -->
	<!-- It simulates if the "grouping" were a "container" instead. -->		<!-- It simulates if the "grouping" were a "container" instead. -->
	<tcp-client xmlns="urn:ietf:params:xml:ns:yang:ietf-tcp-client">		<tcp-client xmlns="urn:ietf:params:xml:ns:yang:ietf-tcp-client">
	<remote-address>www.example.com</remote-address>		<remote-address>www.example.com</remote-address>
	<remote-port>8443</remote-port>		<remote-port>8443</remote-port>
	<local-address>192.0.2.2</local-address>		<local-address>192.0.2.2</local-address>
	<local-port>12345</local-port>		<local-port>12345</local-port>
	<keepalives>		<keepalives>
	<idle-time>7200</idle-time>		<idle-time>7200</idle-time>
	<max-probes>9</max-probes>		<max-probes>9</max-probes>
	<probe-interval>75</probe-interval>		<probe-interval>75</probe-interval>
	</keepalives>		</keepalives>
	</tcp-client>		</tcp-client>
	This example shows a TCP client configured to connect via a proxy:		This example shows a TCP client configured to connect via a proxy.
			The following example uses the XML [W3C.REC-xml-20081126] encoding.
	<!-- The outermost element below doesn't exist in the data model. -->		<!-- The outermost element below doesn't exist in the data model. -->
	<!-- It simulates if the "grouping" were a "container" instead. -->		<!-- It simulates if the "grouping" were a "container" instead. -->
	<tcp-client xmlns="urn:ietf:params:xml:ns:yang:ietf-tcp-client">		<tcp-client xmlns="urn:ietf:params:xml:ns:yang:ietf-tcp-client">
	<remote-address>www.example.com</remote-address>		<remote-address>www.example.com</remote-address>
	<remote-port>8443</remote-port>		<remote-port>8443</remote-port>
	<local-address>192.0.2.2</local-address>		<local-address>192.0.2.2</local-address>
	<local-port>12345</local-port>		<local-port>12345</local-port>
	<proxy-server>		<proxy-server>
	skipping to change at line 730 ¶		skipping to change at line 736 ¶
	feature local-binding-supported {		feature local-binding-supported {
	description		description
	"Indicates that the server supports configuring local		"Indicates that the server supports configuring local
	bindings (i.e., the local address and local port) for		bindings (i.e., the local address and local port) for
	TCP clients.";		TCP clients.";
	}		}
	feature tcp-client-keepalives {		feature tcp-client-keepalives {
	description		description
	"Per socket TCP keepalive parameters are configurable for		"TCP keepalive parameters are configurable for
	TCP clients on the server implementing this feature.";		TCP clients on the server implementing this feature.";
	reference		reference
	"RFC 9293: Transmission Control Protocol (TCP)";		"RFC 9293: Transmission Control Protocol (TCP)";
	}		}
	feature proxy-connect {		feature proxy-connect {
	description		description
	"Indicates the TCP client supports connecting through		"Indicates the TCP client supports connecting through
	TCP proxies.";		TCP proxies.";
	}		}
	skipping to change at line 1038 ¶		skipping to change at line 1044 ¶
	This grouping is presented in the following subsection.		This grouping is presented in the following subsection.
	4.1.2.1. The "tcp-server-grouping" Grouping		4.1.2.1. The "tcp-server-grouping" Grouping
	The following tree diagram [RFC8340] illustrates the "tcp-server-		The following tree diagram [RFC8340] illustrates the "tcp-server-
	grouping" grouping:		grouping" grouping:
	grouping tcp-server-grouping:		grouping tcp-server-grouping:
	+-- local-bind* [local-address]		+-- local-bind* [local-address]
	| +-- local-address? inet:ip-address		| +-- local-address inet:ip-address
	| +-- local-port? inet:port-number		| +-- local-port? inet:port-number
	+---u tcpcmn:tcp-common-grouping		+---u tcpcmn:tcp-common-grouping
	Comments:		Comments:
	* The "local-address" node, which is mandatory, may be configured as		* The "local-address" node, which is mandatory, may be configured as
	an IPv4 address, an IPv6 address, or a wildcard value.		an IPv4 address, an IPv6 address, or a wildcard value.
	* The "local-port" node is not mandatory, but its default value is		* The "local-port" node is not mandatory, but its default value is
	the invalid value "0", thus forcing the consuming data model to		the invalid value "0", thus forcing the consuming data model to
	skipping to change at line 1066 ¶		skipping to change at line 1072 ¶
	The "ietf-tcp-server" module defines only "grouping" statements that		The "ietf-tcp-server" module defines only "grouping" statements that
	are used by other modules to instantiate protocol-accessible nodes.		are used by other modules to instantiate protocol-accessible nodes.
	Thus, this module, when implemented, does not itself define any		Thus, this module, when implemented, does not itself define any
	protocol-accessible nodes.		protocol-accessible nodes.
	4.2. Example Usage		4.2. Example Usage
	This section presents an example showing the "tcp-server-grouping"		This section presents an example showing the "tcp-server-grouping"
	grouping populated with some data.		grouping populated with some data.
			The following example uses the XML [W3C.REC-xml-20081126] encoding.
	<!-- The outermost element below doesn't exist in the data model. -->		<!-- The outermost element below doesn't exist in the data model. -->
	<!-- It simulates if the "grouping" were a "container" instead. -->		<!-- It simulates if the "grouping" were a "container" instead. -->
	<tcp-server xmlns="urn:ietf:params:xml:ns:yang:ietf-tcp-server">		<tcp-server xmlns="urn:ietf:params:xml:ns:yang:ietf-tcp-server">
	<local-bind>		<local-bind>
	<local-address>192.0.2.2</local-address>		<local-address>192.0.2.2</local-address>
	<local-port>49152</local-port>		<local-port>49152</local-port>
	</local-bind>		</local-bind>
	<keepalives>		<keepalives>
	<idle-time>7200</idle-time>		<idle-time>7200</idle-time>
	skipping to change at line 1145 ¶		skipping to change at line 1153 ¶
	description		description
	"Initial version.";		"Initial version.";
	reference		reference
	"RFC 9643: YANG Groupings for TCP Clients and TCP Servers";		"RFC 9643: YANG Groupings for TCP Clients and TCP Servers";
	}		}
	// Features		// Features
	feature tcp-server-keepalives {		feature tcp-server-keepalives {
	description		description
	"Per socket TCP keepalive parameters are configurable for		"TCP keepalive parameters are configurable for
	TCP servers on the server implementing this feature.";		TCP servers on the server implementing this feature.";
	reference		reference
	"RFC 9293: Transmission Control Protocol (TCP)";		"RFC 9293: Transmission Control Protocol (TCP)";
	}		}
	// Groupings		// Groupings
	grouping tcp-server-grouping {		grouping tcp-server-grouping {
	description		description
	"A reusable grouping for configuring a TCP server.		"A reusable grouping for configuring a TCP server.
	skipping to change at line 1528 ¶		skipping to change at line 1536 ¶
	<https://www.rfc-editor.org/info/rfc9645>.		<https://www.rfc-editor.org/info/rfc9645>.
	[SOCKS] Koblas, D. and M. Koblas, "SOCKS", USENIX UNIX Security		[SOCKS] Koblas, D. and M. Koblas, "SOCKS", USENIX UNIX Security
	Symposium III, September 1992, <https://www.usenix.org/leg		Symposium III, September 1992, <https://www.usenix.org/leg
	acy/publications/library/proceedings/sec92/full_papers/		acy/publications/library/proceedings/sec92/full_papers/
	koblas.pdf>.		koblas.pdf>.
	[SOCKS_4A] Lee, Y., "SOCKS 4A: A Simple Extension to SOCKS 4		[SOCKS_4A] Lee, Y., "SOCKS 4A: A Simple Extension to SOCKS 4
	Protocol", <https://www.openssh.com/txt/socks4a.protocol>.		Protocol", <https://www.openssh.com/txt/socks4a.protocol>.
			[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/>.
	Acknowledgements		Acknowledgements
	The authors would like to thank the following for lively discussions		The authors would like to thank the following for lively discussions
	on list and in the halls (ordered by first name): Éric Vyncke, Joe		on list and in the halls (ordered by first name): Éric Vyncke, Joe
	Clarke, Jürgen Schönwälder, Ladislav Lhotka, Mallory Knodel, Martin		Clarke, Jürgen Schönwälder, Ladislav Lhotka, Mallory Knodel, Martin
	Duke, Michael Tüxen, Mohamed Boucadair, Nancy Cam-Winget, Nick		Duke, Michael Tüxen, Mohamed Boucadair, Nancy Cam-Winget, Nick
	Hancock, Per Andersson, Rob Wilton, Roman Danyliw, Tom Petch, and Wim		Hancock, Per Andersson, Rob Wilton, Roman Danyliw, Tom Petch, and Wim
	Henderickx.		Henderickx.
	Authors' Addresses		Authors' Addresses
	Kent Watsen		Kent Watsen
	Watsen Networks		Watsen Networks
	Email: kent+ietf@watsen.net		Email: kent+ietf@watsen.net
	Michael Scharf		Michael Scharf
	Hochschule Esslingen - University of Applied Sciences		Hochschule Esslingen
			University of Applied Sciences
			Kanalstr. 33
			73728 Esslingen am Neckar
			Germany
	Email: michael.scharf@hs-esslingen.de		Email: michael.scharf@hs-esslingen.de
End of changes. 25 change blocks.
	30 lines changed or deleted		49 lines changed or added
This html diff was produced by rfcdiff 1.48.