rfc9754v1.txt		rfc9754.txt
	Internet Engineering Task Force (IETF) T. Haynes		Internet Engineering Task Force (IETF) T. Haynes
	Request for Comments: 9754 T. Myklebust		Request for Comments: 9754 T. Myklebust
	Category: Standards Track Hammerspace		Category: Standards Track Hammerspace
	ISSN: 2070-1721 March 2025		ISSN: 2070-1721 March 2025
	Extending the Opening of Files in NFSv4.2		Extensions for Opening and Delegating Files in NFSv4.2
	Abstract		Abstract
	The Network File System v4 (NFSv4) allows a client to both open a		The Network File System v4 (NFSv4) allows a client to both open a
	file and be granted a delegation of that file. This delegation		file and be granted a delegation of that file. This delegation
	provides the client the right to authoritatively cache metadata on		provides the client the right to authoritatively cache metadata on
	the file locally. This document presents several extensions for both		the file locally. This document presents several extensions for both
	opening the file and delegating it to the client. This document		opening the file and delegating it to the client. This document
	extends NFSv4.2 (see RFC 7863).		extends NFSv4.2 (see RFC 7863).
	skipping to change at line 56 ¶		skipping to change at line 56 ¶
	Table of Contents		Table of Contents
	1. Introduction		1. Introduction
	1.1. Definitions		1.1. Definitions
	1.2. Requirements Language		1.2. Requirements Language
	2. Offline Files		2. Offline Files
	2.1. XDR for the Offline Attribute		2.1. XDR for the Offline Attribute
	3. Determining OPEN Feature Support		3. Determining OPEN Feature Support
	3.1. XDR for Open Arguments		3.1. XDR for Open Arguments
	4. OPEN Grants Only One of Open or Delegation Stateid		4. OPEN Grants Either an Open or a Delegation Stateid
	4.1. Implementation Experience		4.1. Implementation Experience
	5. Proxying of Times		5. Proxying of Times
	5.1. Use Case for NFSv3 Client Proxy		5.1. Use Case for NFSv3 Client Proxy
	5.2. XDR for Proxying of Times		5.2. XDR for Proxying of Times
	6. Extraction of XDR		6. Extraction of XDR
	7. Security Considerations		7. Security Considerations
	8. IANA Considerations		8. IANA Considerations
	9. Normative References		9. Normative References
	Acknowledgments		Acknowledgments
	Authors' Addresses		Authors' Addresses
	skipping to change at line 80 ¶		skipping to change at line 80 ¶
	In the Network File System version 4 (NFSv4), a client may be granted		In the Network File System version 4 (NFSv4), a client may be granted
	a delegation for a file (see Section 1.8.4 of [RFC8881]). This		a delegation for a file (see Section 1.8.4 of [RFC8881]). This
	allows the client to act as the authority for the file's data and		allows the client to act as the authority for the file's data and
	metadata. This document presents a number of extensions that enhance		metadata. This document presents a number of extensions that enhance
	the functionality of opens and delegations. These allow the client		the functionality of opens and delegations. These allow the client
	to:		to:
	* detect an offline file, which may require significant effort to		* detect an offline file, which may require significant effort to
	obtain;		obtain;
	* determine which extensions of OPEN flags (see Section 18.16 of		* determine which extensions of OPEN flags are supported by the
	[RFC8881]) are supported by the server;		server;
	* retrieve either the open or delegation stateid (see Section 8.2 of		* retrieve either the open or delegation stateid, but not both
	[RFC8881]), but not both simultaneously, during the OPEN		simultaneously, during the OPEN procedure; and
	procedure; and
	* cache both the access and modify timestamps, thereby reducing the		* cache both the access and modify timestamps, thereby reducing the
	frequency with which the client must query the server for this		frequency with which the client must query the server for this
	information.		information.
	Using the process detailed in [RFC8178], the revisions in this		Using the process detailed in [RFC8178], the revisions in this
	document become an extension of NFSv4.2 [RFC7862]. They are built on		document become an extension of NFSv4.2 [RFC7862]. They are built on
	top of the External Data Representation (XDR) [RFC4506] generated		top of the External Data Representation (XDR) [RFC4506] generated
	from [RFC7863].		from [RFC7863].
	skipping to change at line 115 ¶		skipping to change at line 114 ¶
	cloud, and the cost is a monetary one in downloading the file.		cloud, and the cost is a monetary one in downloading the file.
	proxy: The proxying of attributes occurs when a client has the		proxy: The proxying of attributes occurs when a client has the
	authority, as granted by the appropriate delegation, to represent		authority, as granted by the appropriate delegation, to represent
	the attributes normally maintained by the server. For read		the attributes normally maintained by the server. For read
	attributes, this occurs when the client has either a read or write		attributes, this occurs when the client has either a read or write
	delegation for the file. For write attributes, this occurs when		delegation for the file. For write attributes, this occurs when
	the client has a write delegation for the file. The client having		the client has a write delegation for the file. The client having
	this authority is the "proxy" for those attributes.		this authority is the "proxy" for those attributes.
			Further, the definitions of the following terms are referenced as
			follows:
			* CB_GETATTR (Section 20.1 of [RFC8881])
			* change (Section 5.8.1.4 of [RFC8881])
			* CLOSE (Section 18.2 of [RFC8881])
			* compound (Section 2.3 of [RFC8881])
			* DELEGRETURN (Section 18.6 of [RFC8881])
			* GETATTR (Section 18.7 of [RFC8881])
			* LAYOUTGET (Section 18.43 of [RFC8881])
			* LOCK (Section 18.10 of [RFC8881])
			* NFS4ERR_DELAY (Section 15.1.1.3 of [RFC8881])
			* OPEN (Section 18.16 of [RFC8881])
			* open_delegation_type4 (Section 18.16.1 of [RFC8881])
			* READ (Section 18.22 of [RFC8881])
			* READDIR (Section 18.23 of [RFC8881])
			* SETATTR (Section 18.30 of [RFC8881])
			* stateid (Section 8.2 of [RFC8881])
			* time_access (Section 5.8.2.37 of [RFC8881])
			* time_metadata (Section 5.8.2.42 of [RFC8881])
			* time_modify (Section 5.8.2.43 of [RFC8881])
			* WRITE (Section 18.32 of [RFC8881])
	1.2. Requirements Language		1.2. Requirements Language
	The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",		The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
	"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and		"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
	"OPTIONAL" in this document are to be interpreted as described in		"OPTIONAL" in this document are to be interpreted as described in
	BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all		BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
	capitals, as shown here.		capitals, as shown here.
	2. Offline Files		2. Offline Files
	If a file is offline, then the server has immediate high-performance		If a file is offline, then the server has immediate high-performance
	access to the file's attributes, but not to the file's content. The		access to the file's attributes, but not to the file's content. The
	action of retrieving the data content is expensive, to the extent		action of retrieving the data content is expensive, to the extent
	that the content should only be retrieved if it is going to be used.		that the content should only be retrieved if it is going to be used.
	For example, a graphical file manager (such as Finder in Mac OS X)		For example, a graphical file manager (such as Finder in Mac OS X)
	may want to access the beginning of the file to preview it for a user		may want to access the beginning of the file to preview it for a user
	who is hovering their pointer over the file name and not accessing it		who is hovering their pointer over the file name and not accessing it
	otherwise. If the file is retrieved, it will most likely be either		otherwise. If the file is retrieved, it will most likely be either
	immediately thrown away or returned.		immediately thrown away or returned.
	A compound (see Section 2.3 of [RFC8881]) with a GETATTR (see		A compound with a GETATTR or READDIR can report the file's attributes
	Section 18.7 of [RFC8881]) or READDIR (see Section 18.23 of		without bringing the file online. However, either an OPEN or a
	[RFC8881]) can report the file's attributes without bringing the file		LAYOUTGET might cause the file server to retrieve the archived data
	online. However, either an OPEN or a LAYOUTGET (see Section 18.43 of
	[RFC8881]) might cause the file server to retrieve the archived data
	contents, bringing the file online. For non-parallel NFS systems		contents, bringing the file online. For non-parallel NFS systems
	(see Section 12 of [RFC8881]), the OPEN operation requires a		(see Section 12 of [RFC8881]), the OPEN operation requires a
	filehandle to the data content. For parallel NFS (pNFS) systems, the		filehandle to retrieve the data content. For parallel NFS (pNFS)
	filehandle retrieved from an OPEN need not cause the data content to		systems, the filehandle retrieved from an OPEN need not cause the
	be retrieved. However, when the LAYOUTGET operation is processed, a		data content to be retrieved. However, when the LAYOUTGET operation
	layout-type-specific mapping will cause the data content to be		is processed, a layout-type-specific mapping will cause the data
	retrieved from offline storage.		content to be retrieved from offline storage.
	If the client is not aware that the file is offline, it might		If the client is not aware that the file is offline, it might
	inadvertently open the file to determine what type of file it is		inadvertently open the file to determine what type of file it is
	accessing. By interrogating the new attribute fattr4_offline, a		accessing. By interrogating the new attribute fattr4_offline, a
	client can predetermine the availability of the file, avoiding the		client can predetermine the availability of the file, avoiding the
	need to open it at all. Being offline might also involve situations		need to open it at all. Being offline might also involve situations
	in which the file is archived in the cloud, i.e., there can be an		in which the file is archived in the cloud, i.e., there can be an
	expense in both retrieving the file to bring it online and in sending		expense in both retrieving the file to bring it online and in sending
	the file back to offline status.		the file back to offline status.
	skipping to change at line 170 ¶		skipping to change at line 208 ¶
	///		///
	/// typedef bool fattr4_offline;		/// typedef bool fattr4_offline;
	///		///
	///		///
	/// const FATTR4_OFFLINE = 83;		/// const FATTR4_OFFLINE = 83;
	///		///
	<CODE ENDS>		<CODE ENDS>
	3. Determining OPEN Feature Support		3. Determining OPEN Feature Support
	[RFC8178] (see Section 4.4.2) allows for extending a particular minor		Section 4.4.2 of [RFC8178] allows for extending a particular minor
	version of the NFSv4 protocol without requiring the definition of a		version of the NFSv4 protocol without requiring the definition of a
	new minor version. The client can probe the capabilities of the		new minor version. The client can probe the capabilities of the
	server and, based on the result, determine if both it and the server		server and, based on the result, determine if both it and the server
	support optional features not previously specified as part of the		support optional features not previously specified as part of the
	minor version.		minor version.
	The fattr4_open_arguments attribute is a new XDR extension that		The fattr4_open_arguments attribute is a new XDR extension that
	provides helpful support when the OPEN procedure is extended in such		provides helpful support when the OPEN procedure is extended in such
	a fashion. It models all of the parameters via bitmap4 data		a fashion. It models all of the parameters via bitmap4 data
	structures, which allows for the addition of a new flag to any of the		structures, which allows for the addition of a new flag to any of the
	OPEN arguments (see Section 18.16.1 of [RFC8881]). The scope of this		OPEN arguments. The scope of this attribute applies to all objects
	attribute applies to all objects with a matching fsid.		with a matching fsid.
	Two new flags are provided:		Two new flags are provided:
	* OPEN4_SHARE_ACCESS_WANT_OPEN_XOR_DELEGATION (see Section 4)		* OPEN4_SHARE_ACCESS_WANT_OPEN_XOR_DELEGATION (see Section 4)
	* OPEN4_SHARE_ACCESS_WANT_DELEG_TIMESTAMPS (see Section 5)		* OPEN4_SHARE_ACCESS_WANT_DELEG_TIMESTAMPS (see Section 5)
	Subsequent extensions can use this framework when introducing new		Subsequent extensions can use this framework when introducing new
	OPTIONAL functionality to OPEN by creating a new flag for each		OPTIONAL functionality to OPEN by creating a new flag for each
	OPTIONAL parameter.		OPTIONAL parameter.
	skipping to change at line 281 ¶		skipping to change at line 319 ¶
	/// const FATTR4_OPEN_ARGUMENTS = 86;		/// const FATTR4_OPEN_ARGUMENTS = 86;
	///		///
	///		///
	/// const OPEN4_SHARE_ACCESS_WANT_OPEN_XOR_DELEGATION = 0x200000;		/// const OPEN4_SHARE_ACCESS_WANT_OPEN_XOR_DELEGATION = 0x200000;
	///		///
	///		///
	/// const OPEN4_RESULT_NO_OPEN_STATEID = 0x00000010;		/// const OPEN4_RESULT_NO_OPEN_STATEID = 0x00000010;
	///		///
	<CODE ENDS>		<CODE ENDS>
	4. OPEN Grants Only One of Open or Delegation Stateid		4. OPEN Grants Either an Open or a Delegation Stateid
	The OPEN (see Section 18.16 of [RFC8881]) procedure returns an open		The OPEN procedure returns an open stateid to the client to reference
	stateid to the client to reference the state of the file. The client		the state of the file. The client could also request a delegation
	could also request a delegation stateid in the OPEN arguments. The		stateid in the OPEN arguments. The file can be considered open for
	file can be considered open for the client as long as the count of		the client as long as the count of open and delegated stateids is
	open and delegated stateids is greater than 0. Either type of		greater than 0. Either type of stateid is sufficient to enable the
	stateid is sufficient to enable the server to treat the file as if it		server to treat the file as if it were open, which allows READ,
	were open, which allows READ (see Section 18.22 of [RFC8881]), WRITE		WRITE, LOCK, and LAYOUTGET operations to proceed. If the client gets
	(see Section 18.32 of [RFC8881]), LOCK (see Section 18.10 of		both an open and a delegation stateid as part of the OPEN, then it
	[RFC8881]), and LAYOUTGET (see Section 18.43 of [RFC8881]) operations		has to return them both to the server. A further consideration is
	to proceed. If the client gets both an open and a delegation stateid		that during each operation, the client can send a costly GETATTR.
	as part of the OPEN, then it has to return them both to the server.
	A further consideration is that during each operation, the client can
	send a costly GETATTR (see Section 18.7 of [RFC8881]).
	If the client knows that the server supports the		If the client knows that the server supports the
	OPEN4_SHARE_ACCESS_WANT_OPEN_XOR_DELEGATION flag (as determined by an		OPEN4_SHARE_ACCESS_WANT_OPEN_XOR_DELEGATION flag (as determined by an
	earlier GETATTR operation that queried for the fattr4_open_arguments		earlier GETATTR operation that queried for the fattr4_open_arguments
	attribute), then the client can supply that flag during the OPEN and		attribute), then the client can supply that flag during the OPEN and
	get either an open or a delegation stateid.		get either an open or a delegation stateid.
	The client is already prepared to not get a delegation stateid, even		The client is already prepared to not get a delegation stateid, even
	if requested. In order to not send an open stateid, the server MUST		if requested. In order to not send an open stateid, the server MUST
	indicate that fact with the result flag of		indicate that fact with the result flag of
	OPEN4_RESULT_NO_OPEN_STATEID. The open stateid field,		OPEN4_RESULT_NO_OPEN_STATEID. The open stateid field,
	OPEN4resok.stateid (see Section 18.16.2 of [RFC8881]), MUST be set to		OPEN4resok.stateid, MUST be set to the special all-zero stateid in
	the special all-zero stateid in this case.		this case.
	Note that the OPEN4_SHARE_ACCESS_WANT_OPEN_XOR_DELEGATION flag is a		Note that the OPEN4_SHARE_ACCESS_WANT_OPEN_XOR_DELEGATION flag is a
	hint. The server might return both stateids. Consider the scenario		hint. The server might return both stateids. Consider the scenario
	in which the client opens a file for read-only (with		in which the client opens a file for read-only (with
	OPEN4_SHARE_ACCESS_WANT_OPEN_XOR_DELEGATION set) and only gets an		OPEN4_SHARE_ACCESS_WANT_OPEN_XOR_DELEGATION set) and only gets an
	open stateid. If the client then opens the file for read-write (with		open stateid. If the client then opens the file for read-write (with
	OPEN4_SHARE_ACCESS_WANT_OPEN_XOR_DELEGATION set), then the server has		OPEN4_SHARE_ACCESS_WANT_OPEN_XOR_DELEGATION set), the server can
	three options:		return one of the following three options:
	1. Only an open stateid with the correct seqid.		1. Only an open stateid with the correct seqid.
	2. Only a delegation stateid with the open stateid now having an		2. Only a delegation stateid with the open stateid now having an
	incorrect seqid as it needs to be upgraded.		incorrect seqid as it needs to be upgraded.
	3. Both an open stateid (which will be upgraded) and a delegation		3. Both an open stateid (which will be upgraded) and a delegation
	stateid.		stateid.
	In this scenario, returning just a delegation stateid would hide		In this scenario, returning just a delegation stateid would hide
	information from the client. If the client already has an open		information from the client. If the client already has an open
	stateid, then the server SHOULD ignore the		stateid, then the server SHOULD ignore the
	OPEN4_SHARE_ACCESS_WANT_OPEN_XOR_DELEGATION flag and return both the		OPEN4_SHARE_ACCESS_WANT_OPEN_XOR_DELEGATION flag and return both the
	open and delegation stateids.		open and delegation stateids.
	4.1. Implementation Experience		4.1. Implementation Experience
	The CLOSE operation (see Section 18.2 of [RFC8881]) neither		The CLOSE operation neither explicitly nor implicitly releases any
	explicitly nor implicitly releases any delegation stateids. This is		delegation stateids. This is not symmetrical with the OPEN
	not symmetrical with the OPEN operation, which can grant both an open		operation, which can grant both an open and a delegation stateid.
	and a delegation stateid. This specification could have tried to		This specification could have tried to extend the CLOSE operation to
	extend the CLOSE operation to release both stateids, but		release both stateids, but implementation experience shows that is
	implementation experience shows that is more costly than the approach		more costly than the approach that has been proposed.
	that has been proposed.
	Consider a small workload of creating a file with content. That		Consider a small workload of creating a file with content. This
	takes three synchronous operations and one asynchronous operation		involves three synchronous operations and one asynchronous operation
	with existing implementations. The first synchronous operation has		with existing implementations:
	to OPEN the file; the second synchronous one performs the WRITE to
	the file; the third synchronous one has to CLOSE the file; and the		* The first synchronous operation has to OPEN the file.
	asynchronous one uses DELEGRETURN (see Section 18.6 of [RFC8881]) to
	return the delegation stateid.		* The second synchronous operation performs the WRITE to the file.
			* The third synchronous operation has to CLOSE the file.
			* The asynchronous operation uses DELEGRETURN to return the
			delegation stateid.
	<CODE BEGINS>		<CODE BEGINS>
	SEQ PUTFH OPEN GETFH GETATTR		SEQ PUTFH OPEN GETFH GETATTR
	SEQ PUTFH WRITE GETATTR		SEQ PUTFH WRITE GETATTR
	SEQ PUTFH CLOSE		SEQ PUTFH CLOSE
	...		...
	SEQ PUTFH DELEGRETURN		SEQ PUTFH DELEGRETURN
	<CODE ENDS>		<CODE ENDS>
	With the proposed approach of setting the		With the proposed approach of setting the
	skipping to change at line 384 ¶		skipping to change at line 423 ¶
	This approach reduces the cost of synchronous operations by 33% and		This approach reduces the cost of synchronous operations by 33% and
	the total number of operations by 25%. Contrast that with the		the total number of operations by 25%. Contrast that with the
	alternative proposal of having CLOSE return both stateids, which		alternative proposal of having CLOSE return both stateids, which
	would not reduce the number of synchronous operations.		would not reduce the number of synchronous operations.
	5. Proxying of Times		5. Proxying of Times
	When a client is granted a write delegation on a file, it becomes the		When a client is granted a write delegation on a file, it becomes the
	authority for the file contents and associated attributes. If the		authority for the file contents and associated attributes. If the
	server queries the client as to the state of the file via a		server queries the client as to the state of the file via a
	CB_GETATTR (see Section 20.1 of [RFC8881]), then according to the		CB_GETATTR, then according to the unextended NFSv4 protocol, it can
	unextended NFSv4 protocol, it can only determine the size of the file		only determine the size of the file and the change attribute. In the
	and the change attribute. In the case of the client holding the		case of the client holding the delegation, it has the current values
	delegation, it has the current values of the access and modify times.		of the access and modify times. There is no way that other clients
	There is no way that other clients can have access to these values.		can have access to these values. To notify the server of the proxied
	To notify the server of the proxied values, the client could send a		values, the client could send a compound of the form SEQ, PUTFH,
	compound of the form SEQ, PUTFH, SETATTR (time_modify | time_access),		SETATTR (time_modify | time_access), DELEGRETURN; however, the
	DELEGRETURN; however, the SETATTR operation (see Section 18.30 of		SETATTR operation would cause either or both of the change attribute
	[RFC8881]) would cause either or both of the change attribute (see		or time_metadata attribute to be modified to the current time on the
	Section 5.8.1.4 of [RFC8881]) or time_metadata attribute (see		server. There is no current provision to obtain these values before
	Section 5.8.2.42 of [RFC8881]) to be modified to the current time on		delegation return using CB_GETATTR. As a result, it cannot pass on
	the server. There is no current provision to obtain these values		these times to an application expecting POSIX compliance, as is often
	before delegation return using CB_GETATTR. As a result, it cannot		necessary for correct operation.
	pass these times up to an application expecting POSIX compliance, as
	is often necessary for correct operation.
	With the addition of the new OPEN4_SHARE_ACCESS_WANT_DELEG_TIMESTAMPS		With the addition of the new OPEN4_SHARE_ACCESS_WANT_DELEG_TIMESTAMPS
	flag, the client and server can negotiate that the client will be the		flag, the client and server can negotiate that the client will be the
	authority for these values, and upon return of the delegation stateid		authority for these values, and upon return of the delegation stateid
	via a DELEGRETURN (see Section 18.6 of [RFC8881]), the times will be		via a DELEGRETURN, the times will be passed back to the server. If
	passed back to the server. If the server is queried by another		the server is queried by another client for either the size or the
	client for either the size or the times, it will need to use a		times, it will need to use a CB_GETATTR to query the client that
	CB_GETATTR to query the client that holds the delegation (see		holds the delegation.
	Section 20.1 of [RFC8881]).
	If a server informs the client via the fattr4_open_arguments		If a server informs the client via the fattr4_open_arguments
	attribute that it supports		attribute that it supports
	OPEN_ARGS_SHARE_ACCESS_WANT_DELEG_TIMESTAMPS and it returns a valid		OPEN_ARGS_SHARE_ACCESS_WANT_DELEG_TIMESTAMPS and it returns a valid
	delegation stateid for an OPEN operation that sets the		delegation stateid for an OPEN operation that sets the
	OPEN4_SHARE_ACCESS_WANT_DELEG_TIMESTAMPS flag, then it MUST query the		OPEN4_SHARE_ACCESS_WANT_DELEG_TIMESTAMPS flag, then it MUST query the
	client via a CB_GETATTR for the fattr4_time_deleg_access attribute		client via a CB_GETATTR for the fattr4_time_deleg_access attribute
	(see Section 5.2) and the fattr4_time_deleg_modify attribute (see		(see Section 5.2) and the fattr4_time_deleg_modify attribute (see
	Section 5.2). (Note that the change time can be derived from the		Section 5.2). (Note that the change time can be derived from the
	modify time.) Further, when it gets a SETATTR with those attributes		modify time.) Further, when a server gets a SETATTR with those
	set, then it MUST accept those fattr4_time_deleg_access attribute and		attributes set, then it MUST accept those changes in the
	fattr4_time_deleg_modify attribute changes and derive the change time		fattr4_time_deleg_access and fattr4_time_deleg_modify attributes and
	or reject the changes with NFS4ERR_DELAY (see Section 15.1.1.3 of		derive the change time, or it MUST reject the changes with
	[RFC8881]).		NFS4ERR_DELAY.
			When the server grants a delegation stateid, it MUST inform the
			client by setting the appropriate flag in the open_delegation_type4
			response. The server MUST set OPEN_DELEGATE_READ_ATTRS_DELEG when it
			grants a read attribute delegation and MUST set
			OPEN_DELEGATE_WRITE_ATTRS_DELEG when it grants a write attribute
			delegation.
	These new attributes are invalid to be used with GETATTR, VERIFY, and		These new attributes are invalid to be used with GETATTR, VERIFY, and
	NVERIFY, and they can only be used with CB_GETATTR and SETATTR by a		NVERIFY, and they can only be used with CB_GETATTR and SETATTR by a
	client holding an appropriate delegation. The SETATTR SHOULD either		client holding an appropriate delegation. The SETATTR SHOULD be
	be in a separate compound before the one containing the DELEGRETURN		either 1) in a separate compound before the one containing the
	or when in the same compound, as an operation before the DELEGRETURN.		DELEGRETURN or 2) in the same compound as an operation before the
	Failure to properly sequence the operations may lead to race		DELEGRETURN. Failure to properly sequence the operations may lead to
	conditions.		race conditions.
	A key prerequisite of this approach is that the server and client are		A key prerequisite of this approach is that the server and client are
	in time synchronization with each other. Note that while the base		in time synchronization with each other. Note that while the base
	NFSv4.2 does not require such synchronization, the use of RPCSEC_GSS		NFSv4.2 does not require such synchronization, the use of RPCSEC_GSS
	typically makes such a requirement. When the client presents either		typically makes such a requirement. When the client presents either
	the fattr4_time_deleg_access or the fattr4_time_deleg_modify		the fattr4_time_deleg_access or the fattr4_time_deleg_modify
	attribute to the server, the server MUST decide for both of them		attribute to the server, the server MUST decide for both of them
	whether the time presented is:		whether the time presented is:
	* before the corresponding time_access attribute (see		* before the corresponding time_access attribute or time_modify
	Section 5.8.2.37 of [RFC8881]) or time_modify attribute (see		attribute on the file, or
	Section 5.8.2.43 of [RFC8881]) on the file, or
	* past the current server time.		* past the current server time.
	When the time presented is before the original time, then the update		When the time presented is before the original time, then the update
	is ignored. When the time presented is in the future, the server can		is ignored. When the time presented is in the future, the server can
	either clamp the new time to the current time or return NFS4ERR_DELAY		either clamp the new time to the current time or return NFS4ERR_DELAY
	to the client, allowing it to retry. Note that if the clock skew is		to the client, allowing it to retry. Note that if the clock skew is
	large, the delay approach would result in access to the file being		large, the delay approach would result in access to the file being
	denied until the clock skew is exceeded.		denied until the clock skew is exceeded.
	A change in the access time MUST NOT advance the change time, also		A change in the access time MUST NOT advance the change time, also
	known as the time_metadata attribute (see Section 5.8.2.42 of		known as the time_metadata attribute. However, a change in the
	[RFC8881]). However, a change in the modify time might advance the		modify time might advance the change time (and in turn, the change
	change time (and in turn, the change attribute; see Section 5.8.1.4		attribute). If the modify time is greater than the change time and
	of [RFC8881]). If the modify time is greater than the change time		before the current time, then the change time is adjusted to the
	and before the current time, then the change time is adjusted to the
	modify time and not the current time (as is most likely done on most		modify time and not the current time (as is most likely done on most
	SETATTR calls that change the metadata). If the modify time is in		SETATTR calls that change the metadata). If the modify time is in
	the future, it will be clamped to the current time.		the future, it will be clamped to the current time.
	Note that each of the possible times (access, modify, and change) are		Note that each of the possible times (access, modify, and change) are
	compared to the current time. They should all be compared against		compared to the current time. They should all be compared against
	the same time value for the current time (i.e., they do not retrieve		the same time value for the current time (i.e., they do not retrieve
	a different value of the current time for each calculation).		a different value of the current time for each calculation).
	If the client sets the OPEN4_SHARE_ACCESS_WANT_DELEG_TIMESTAMPS flag		If the client sets the OPEN4_SHARE_ACCESS_WANT_DELEG_TIMESTAMPS flag
	skipping to change at line 507 ¶		skipping to change at line 548 ¶
	/// %/*		/// %/*
	/// % * New RECOMMENDED Attribute for		/// % * New RECOMMENDED Attribute for
	/// % * delegation caching of times		/// % * delegation caching of times
	/// % */		/// % */
	/// const FATTR4_TIME_DELEG_ACCESS = 84;		/// const FATTR4_TIME_DELEG_ACCESS = 84;
	/// const FATTR4_TIME_DELEG_MODIFY = 85;		/// const FATTR4_TIME_DELEG_MODIFY = 85;
	///		///
	///		///
	/// const OPEN4_SHARE_ACCESS_WANT_DELEG_TIMESTAMPS = 0x100000;		/// const OPEN4_SHARE_ACCESS_WANT_DELEG_TIMESTAMPS = 0x100000;
	///		///
			/// enum open_delegation_type4 {
			/// OPEN_DELEGATE_NONE = 0,
			/// OPEN_DELEGATE_READ = 1,
			/// OPEN_DELEGATE_WRITE = 2,
			/// OPEN_DELEGATE_NONE_EXT = 3, /* new to v4.1 */
			/// OPEN_DELEGATE_READ_ATTRS_DELEG = 4,
			/// OPEN_DELEGATE_WRITE_ATTRS_DELEG = 5
			/// };
	<CODE ENDS>		<CODE ENDS>
	6. Extraction of XDR		6. Extraction of XDR
	This document contains the XDR [RFC4506] description of the new open		This document contains the XDR [RFC4506] description of the new open
	flags for delegating the file to the client. The XDR description is		flags for delegating the file to the client. The XDR description is
	embedded in this document in a way that makes it simple for the		embedded in this document in a way that makes it simple for the
	reader to extract into a ready-to-compile form. The reader can feed		reader to extract into a ready-to-compile form. The reader can feed
	this document into the following shell script to produce the machine-		this document into the following shell script to produce the machine-
	readable XDR description of the new flags:		readable XDR description of the new flags:
	skipping to change at line 531 ¶		skipping to change at line 580 ¶
	<CODE ENDS>		<CODE ENDS>
	That is, if the above script is stored in a file called "extract.sh"		That is, if the above script is stored in a file called "extract.sh"
	and this document is in a file called "spec.txt", then the reader can		and this document is in a file called "spec.txt", then the reader can
	do the following:		do the following:
	<CODE BEGINS>		<CODE BEGINS>
	sh extract.sh < spec.txt > delstid_prot.x		sh extract.sh < spec.txt > delstid_prot.x
	<CODE ENDS>		<CODE ENDS>
	The effect of the script is to remove leading white space from each		The effect of the script is to remove leading blank space from each
	line, plus a sentinel sequence of "///". XDR descriptions with the		line, plus a sentinel sequence of "///". XDR descriptions with the
	sentinel sequence are embedded throughout the document.		sentinel sequence are embedded throughout the document.
	Note that the XDR code contained in this document depends on types		Note that the XDR code contained in this document depends on types
	from the NFSv4.2 nfs4_prot.x file (generated from [RFC7863]). This		from the NFSv4.2 nfs4_prot.x file (generated from [RFC7863]). This
	includes both nfs types that end with a 4 (such as offset4 and		includes both nfs types that end with a 4 (such as offset4 and
	length4) as well as more generic types (such as uint32_t and		length4) as well as more generic types (such as uint32_t and
	uint64_t).		uint64_t).
	While the XDR can be appended to that from [RFC7863], the various		While the XDR can be appended to that from [RFC7863], the various
	code snippets belong in their respective areas of that XDR.		code snippets belong in their respective areas of that XDR.
	7. Security Considerations		7. Security Considerations
	While this document extends some capabilities for client delegation,		While this document extends some capabilities for client delegation,
	there are no new security concerns. The client cannot be queried by		there are no new security concerns. The client cannot be queried by
	other clients as to the cached attributes. The client could report		other clients as to the cached attributes. The client could report
	false data for the cached attributes, but it already has this ability		false data for the cached attributes, but it already has this ability
	via a SETATTR operation (see Section 18.30 of [RFC8881]).		via a SETATTR operation.
	8. IANA Considerations		8. IANA Considerations
	This document has no IANA actions.		This document has no IANA actions.
	9. Normative References		9. Normative References
	[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate		[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
	Requirement Levels", BCP 14, RFC 2119,		Requirement Levels", BCP 14, RFC 2119,
	DOI 10.17487/RFC2119, March 1997,		DOI 10.17487/RFC2119, March 1997,
End of changes. 24 change blocks.
	92 lines changed or deleted		141 lines changed or added
This html diff was produced by rfcdiff 1.48.