rfc9754.original   rfc9754.txt 
Network File System Version 4 T. Haynes Internet Engineering Task Force (IETF) T. Haynes
Internet-Draft T. Myklebust Request for Comments: 9754 T. Myklebust
Intended status: Standards Track Hammerspace Category: Standards Track Hammerspace
Expires: 5 April 2025 2 October 2024 ISSN: 2070-1721 March 2025
Extending the Opening of Files in NFSv4.2 Extensions for Opening and Delegating Files in NFSv4.2
draft-ietf-nfsv4-delstid-08
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
the opening and delegating of the file to the client. This document opening the file and delegating it to the client. This document
extends NFSv4.2 (see RFC7863). extends NFSv4.2 (see RFC 7863).
Note
This note is to be removed before publishing as an RFC.
Discussion of this draft takes place on the NFSv4 working group
mailing list (nfsv4@ietf.org), which is archived at
https://mailarchive.ietf.org/arch/browse/nfsv4/. Working Group
information can be found at https://datatracker.ietf.org/wg/nfsv4/
about/.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This is an Internet Standards Track document.
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 This document is a product of the Internet Engineering Task Force
and may be updated, replaced, or obsoleted by other documents at any (IETF). It represents the consensus of the IETF community. It has
time. It is inappropriate to use Internet-Drafts as reference received public review and has been approved for publication by the
material or to cite them other than as "work in progress." Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 7841.
This Internet-Draft will expire on 5 April 2025. Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
https://www.rfc-editor.org/info/rfc9754.
Copyright Notice Copyright Notice
Copyright (c) 2024 IETF Trust and the persons identified as the Copyright (c) 2025 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/ Provisions Relating to IETF Documents
license-info) in effect on the date of publication of this document. (https://trustee.ietf.org/license-info) in effect on the date of
Please review these documents carefully, as they describe your rights publication of this document. Please review these documents
and restrictions with respect to this document. Code Components carefully, as they describe your rights and restrictions with respect
extracted from this document must include Revised BSD License text as to this document. Code Components extracted from this document must
described in Section 4.e of the Trust Legal Provisions and are include Revised BSD License text as described in Section 4.e of the
provided without warranty as described in the Revised BSD License. Trust Legal Provisions and are provided without warranty as described
in the Revised BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction
1.1. Definitions . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Definitions
1.2. Requirements Language . . . . . . . . . . . . . . . . . . 3 1.2. Requirements Language
2. Offline Files . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Offline Files
2.1. XDR for Offline Attribute . . . . . . . . . . . . . . . . 4 2.1. XDR for the Offline Attribute
3. Determining OPEN Feature Support . . . . . . . . . . . . . . 5 3. Determining OPEN Feature Support
3.1. XDR for Open Arguments . . . . . . . . . . . . . . . . . 5 3.1. XDR for Open Arguments
4. OPEN grants only one of Open or Delegation Stateid . . . . . 7 4. OPEN Grants Either an Open or a Delegation Stateid
4.1. Implementation Experience . . . . . . . . . . . . . . . . 8 4.1. Implementation Experience
5. Proxying of Times . . . . . . . . . . . . . . . . . . . . . . 9 5. Proxying of Times
5.1. Use case: NFSv3 client proxy . . . . . . . . . . . . . . 11 5.1. Use Case for NFSv3 Client Proxy
5.2. XDR for Proxying of Times . . . . . . . . . . . . . . . . 11 5.2. XDR for Proxying of Times
6. Extraction of XDR . . . . . . . . . . . . . . . . . . . . . . 12 6. Extraction of XDR
7. Security Considerations . . . . . . . . . . . . . . . . . . . 13 7. Security Considerations
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 8. IANA Considerations
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 13 9. Normative References
9.1. Normative References . . . . . . . . . . . . . . . . . . 13 Acknowledgments
Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 14 Authors' Addresses
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 14
1. Introduction 1. Introduction
In the Network File System version4 (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 metadata and allows the client to act as the authority for the file's data and
data. This document presents a number of extensions which 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 (see Section 18.16 of * determine which extensions of OPEN flags are supported by the
[RFC8881]) flags are supported by the server. server;
* during the OPEN procedure, retrieve either the open stateid (see * retrieve either the open or delegation stateid, but not both
Section 8.2 of [RFC8881]) or delegation stateid, but not both simultaneously, during the OPEN procedure; and
simultaneously.
* 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].
1.1. Definitions 1.1. Definitions
offline file: A file which exists on a device which is not connected This document uses the following terminology:
offline file: A file that exists on a device that is not connected
to the server. There is typically a cost associated with bringing to the server. There is typically a cost associated with bringing
the file to an online status. Historically this would be a file the file to an online status. Historically, this would be a file
on tape media and the cost would have been finding and loading the on tape media, and the cost would have been finding and loading
tape. A more modern interpretation is that the file is in the the tape. A more modern interpretation is that the file is in the
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: 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
delegations 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 OSX's Finder) may want For example, a graphical file manager (such as Finder in Mac OS X)
to access the beginning of the file to preview it for an user who is may want to access the beginning of the file to preview it for a user
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 either be 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 contents, bringing the file online. For non-parallel NFS systems
[RFC8881]) might cause the file server to retrieve the archived data (see Section 12 of [RFC8881]), the OPEN operation requires a
contents, bringing the file online. For non-parallel NFS (pNFS) filehandle to retrieve the data content. For parallel NFS (pNFS)
systems (see Section 12 of [RFC8881]) , the OPEN operation requires a systems, the filehandle retrieved from an OPEN need not cause the
filehandle to the data content. For pNFS systems, the filehandle data content to be retrieved. However, when the LAYOUTGET operation
retrieved from an OPEN need not cause the data content to be is processed, a layout-type-specific mapping will cause the data
retrieved. But when the LAYOUTGET operation is processed, a layout content to be retrieved from offline storage.
type specific mapping will cause the data 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 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.
2.1. XDR for Offline Attribute 2.1. XDR for the Offline Attribute
<CODE BEGINS> <CODE BEGINS>
/// ///
/// 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 which 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.
Since fattr4_open_arguments is a RECOMMENDED attribute, if the server Since fattr4_open_arguments is a RECOMMENDED attribute, if the server
informs the client via NFS4ERR_ATTRNOTSUPP that it does not support informs the client via NFS4ERR_ATTRNOTSUPP that it does not support
this new attribute, the client MUST take this to mean that the this new attribute, the client MUST take this to mean that the
additional new OPTIONAL functionality to OPEN is also not supported. additional new OPTIONAL functionality to OPEN is also not supported.
Some other concerns are how to process both currently REQUIRED flags Some other concerns are how to process both currently REQUIRED flags
and OPTIONAL flags which become REQUIRED in the future. The server and OPTIONAL flags that become REQUIRED in the future. The server
MUST mark REQUIRED flags as being supported. Note that these flags MUST mark REQUIRED flags as being supported. Note that these flags
MUST only change from OPTIONAL to REQUIRED when the NFSv4 minor MUST only change from OPTIONAL to REQUIRED when the NFSv4 minor
version is incremented. version is incremented.
3.1. XDR for Open Arguments 3.1. XDR for Open Arguments
<CODE BEGINS> <CODE BEGINS>
/// ///
/// struct open_arguments4 { /// struct open_arguments4 {
/// bitmap4 oa_share_access; /// bitmap4 oa_share_access;
skipping to change at page 7, line 21 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.25 of [RFC8881]), WRITE WRITE, LOCK, and LAYOUTGET operations to proceed. If the client gets
(See Section 18.38 of [RFC8881]), LOCK (See Section 18.12 of both an open and a delegation stateid as part of the OPEN, then it
[RFC8881]), and LAYOUTGET (see Section 18.50 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 which 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
only get either an open or 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 read-only (with in which the client opens a file for read-only (with
OPEN4_SHARE_ACCESS_WANT_OPEN_XOR_DELEGATION set) and gets only 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 (which will be upgraded) and a delegation stateid. 3. Both an open stateid (which will be upgraded) and a delegation
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.
which 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 3 synchronous and 1 asynchronous operations with existing involves three synchronous operations and one asynchronous operation
implementations. The first synchronous one has to OPEN the file, the with existing implementations:
second synchronous one performs the WRITE to the file, the third
synchronous one has to CLOSE the file, and the fourth asynchronous * The first synchronous operation has to OPEN the file.
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
OPEN_ARGS_SHARE_ACCESS_WANT_OPEN_XOR_DELEGATION flag during the OPEN, OPEN_ARGS_SHARE_ACCESS_WANT_OPEN_XOR_DELEGATION flag during the OPEN,
the number of operations is always 3. The first two compounds are the number of operations is always three. The first two compounds
still synchronous, but the last is asynchronous. I.e., since the are still synchronous, but the last is asynchronous. That is, since
client no longer has to send a CLOSE operation, it can delay the the client no longer has to send a CLOSE operation, it can delay the
DELEGRETURN until either the server requests it back via delegation DELEGRETURN until either the server requests it back via delegation
recall or garbage collection causes the client to return the stateid. recall or garbage collection causes the client to return the stateid.
<CODE BEGINS> <CODE BEGINS>
SEQ PUTFH OPEN(OPEN_ARGS_SHARE_ACCESS_WANT_OPEN_XOR_DELEGATION) SEQ PUTFH OPEN(OPEN_ARGS_SHARE_ACCESS_WANT_OPEN_XOR_DELEGATION)
GETFH GETATTR GETFH GETATTR
SEQ PUTFH WRITE GETATTR SEQ PUTFH WRITE GETATTR
... ...
SEQ PUTFH DELEGRETURN SEQ PUTFH DELEGRETURN
<CODE ENDS> <CODE ENDS>
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 against 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
While the client could send a compound of the form: SEQ, PUTFH, values, the client could send a compound of the form SEQ, PUTFH,
SETATTR (time_modify | time_access), DELEGRETURN, to notify the SETATTR (time_modify | time_access), DELEGRETURN; however, the
server of the proxied values, that SETATTR (see Section 18.30 of SETATTR operation would cause either or both of the change attribute
[RFC8881]) operation would cause either or both of change (see or time_metadata attribute to be modified to the current time on the
Section 5.8.1.4 of [RFC8881]) or time_metadata (see Section 5.8.2.42 server. There is no current provision to obtain these values before
of [RFC8881]) to be modified to the current time on the server. delegation return using CB_GETATTR. As a result, it cannot pass on
There is no current provision to obtain these values before these times to an application expecting POSIX compliance, as is often
delegation return using CB_GETATTR. As a result, it can not pass necessary for correct operation.
these times up to an application expecting POSIX compliance, as is
often necessary for correct operation.
With the addition of the new flag: With the addition of the new OPEN4_SHARE_ACCESS_WANT_DELEG_TIMESTAMPS
OPEN4_SHARE_ACCESS_WANT_DELEG_TIMESTAMPS, the client and server can flag, the client and server can negotiate that the client will be the
negotiate that the client will be the authority for these values and authority for these values, and upon return of the delegation stateid
upon return of the delegation stateid via a DELEGRETURN (see section via a DELEGRETURN, the times will be passed back to the server. If
18.6 of [RFC8881]), the times will be passed back to the server. If
the server is queried by another client for either the size or the the server is queried by another client for either the size or the
times, it will need to use a CB_GETATTR to query the client which times, it will need to use a CB_GETATTR to query the client that
holds the delegation (see Section 20.1 of [RFC8881]). holds the delegation.
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 which 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 (see client via a CB_GETATTR for the fattr4_time_deleg_access attribute
Section 5.2) attribute and fattr4_time_deleg_modify attribute (see (see Section 5.2) and the fattr4_time_deleg_modify attribute (see
Section 5.2). (The change time can be derived from the modify time.) Section 5.2). (Note that the change time can be derived from the
Further, when it gets a SETATTR with those attributes being set, then modify time.) Further, when a server gets a SETATTR with those
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 can only be used with CB_GETATTR and SETATTR by a client NVERIFY, and they can only be used with CB_GETATTR and SETATTR by a
holding an appropriate delegation. The SETATTR SHOULD either be in a client holding an appropriate delegation. The SETATTR SHOULD be
separate compound before the one containing the DELEGRETURN or when either 1) in a separate compound before the one containing the
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
fattr4_time_deleg_access or fattr4_time_deleg_modify attributes to the fattr4_time_deleg_access or the fattr4_time_deleg_modify
the server, the server MUST decide for both of them whether the time attribute to the server, the server MUST decide for both of them
presented is before the corresponding time_access (see whether the time presented is:
Section 5.8.2.37 of [RFC8881]) or time_modify (see Section 5.8.2.43
of [RFC8881]) attribute on the file or past the current server time. * before the corresponding time_access attribute or time_modify
attribute on the file, or
* 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 it may return either clamp the new time to the current time or return NFS4ERR_DELAY
NFS4ERR_DELAY to the client, allowing it to retry. Note that if the to the client, allowing it to retry. Note that if the clock skew is
clock skew is large, the delay approach would result in access to the large, the delay approach would result in access to the file being
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]), but a change in the modify time might advance the change modify time might advance the change time (and in turn, the change
time (and in turn the change attribute (See Section 5.8.1.4 of attribute). If the modify time is greater than the change time and
[RFC8881]). If the modify time is greater than the change time and
before the current time, then the change time is adjusted to the 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., do not retrieve a the same time value for the current time (i.e., they do not retrieve
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
in an OPEN operation, then it MUST support the in an OPEN operation, then it MUST support the
fattr4_time_deleg_access and fattr4_time_deleg_modify attributes both fattr4_time_deleg_access and fattr4_time_deleg_modify attributes in
in the CB_GETATTR and SETATTR operations. both the CB_GETATTR and SETATTR operations.
5.1. Use case: NFSv3 client proxy 5.1. Use Case for NFSv3 Client Proxy
Consider a NFSv3 client which wants to access data on a server which Consider an NFSv3 client that wants to access data on a server that
only supports NFSv4.2. An implementation may introduce an NFSv3 only supports NFSv4.2. An implementation may introduce an NFSv3
server that functions as an NFSv4.2 client, serving as a gateway server that functions as an NFSv4.2 client, serving as a gateway
between the two otherwise incompatible systems. As NFSv3 is a between the two otherwise incompatible systems. As NFSv3 is a
stateless protocol, the state is not kept on the client, but rather stateless protocol, the state is not kept on the client, but rather
the NFSv3 server. As the NFSv3 server is already managing the state, on the NFSv3 server. As the NFSv3 server is already managing the
it can proxy file delegations to avoid spurious GETATTRs. I.e., as state, it can proxy file delegations to avoid spurious GETATTRs.
the client queries the NFSv3 server for the attributes, they can be That is, as the client queries the NFSv3 server for the attributes,
served without the NFSv3 server sending a GETATTR to the NFSv4.2 they can be served without the NFSv3 server sending a GETATTR to the
server. NFSv4.2 server.
5.2. XDR for Proxying of Times 5.2. XDR for Proxying of Times
<CODE BEGINS> <CODE BEGINS>
/// ///
/// /* /// /*
/// * attributes for the delegation times being /// * attributes for the delegation times being
/// * cached and served by the "client" /// * cached and served by the "client"
/// */ /// */
/// typedef nfstime4 fattr4_time_deleg_access; /// typedef nfstime4 fattr4_time_deleg_access;
/// typedef nfstime4 fattr4_time_deleg_modify; /// typedef nfstime4 fattr4_time_deleg_modify;
/// ///
/// ///
/// %/* /// %/*
/// % * 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 external data representation (XDR) This document contains the XDR [RFC4506] description of the new open
[RFC4506] description of the new open flags for delegating the file flags for delegating the file to the client. The XDR description is
to the client. The XDR description is embedded in this document in a embedded in this document in a way that makes it simple for the
way that makes it simple for the reader to extract into a ready-to- reader to extract into a ready-to-compile form. The reader can feed
compile form. The reader can feed this document into the following this document into the following shell script to produce the machine-
shell script to produce the machine readable XDR description of the readable XDR description of the new flags:
new flags:
<CODE BEGINS> <CODE BEGINS>
#!/bin/sh #!/bin/sh
grep '^ *///' $* | sed 's?^ */// ??' | sed 's?^ *///$??' grep '^ *///' $* | sed 's?^ */// ??' | sed 's?^ *///$??'
<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: 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, length4, includes both nfs types that end with a 4 (such as offset4 and
etc., as well as more generic types such as uint32_t and uint64_t. length4) as well as more generic types (such as uint32_t and
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 we are extending some capabilities for client delegation, there While this document extends some capabilities for client delegation,
are no new security concerns. The client cannot be queried by other there are no new security concerns. The client cannot be queried by
clients as to the cached attributes. The client could report false other clients as to the cached attributes. The client could report
data for the cached attributes, but it already has this ability via a false data for the cached attributes, but it already has this ability
SETATTR operation (see Section 18.30 of [RFC8881]). via a SETATTR operation.
8. IANA Considerations 8. IANA Considerations
There are no IANA considerations. This document has no IANA actions.
9. References
9.1. 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,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC4506] Eisler, M., Ed., "XDR: External Data Representation [RFC4506] Eisler, M., Ed., "XDR: External Data Representation
Standard", STD 67, RFC 4506, DOI 10.17487/RFC4506, May Standard", STD 67, RFC 4506, DOI 10.17487/RFC4506, May
2006, <https://www.rfc-editor.org/info/rfc4506>. 2006, <https://www.rfc-editor.org/info/rfc4506>.
skipping to change at page 14, line 14 skipping to change at line 638
[RFC8178] Noveck, D., "Rules for NFSv4 Extensions and Minor [RFC8178] Noveck, D., "Rules for NFSv4 Extensions and Minor
Versions", RFC 8178, DOI 10.17487/RFC8178, July 2017, Versions", RFC 8178, DOI 10.17487/RFC8178, July 2017,
<https://www.rfc-editor.org/info/rfc8178>. <https://www.rfc-editor.org/info/rfc8178>.
[RFC8881] Noveck, D., Ed. and C. Lever, "Network File System (NFS) [RFC8881] Noveck, D., Ed. and C. Lever, "Network File System (NFS)
Version 4 Minor Version 1 Protocol", RFC 8881, Version 4 Minor Version 1 Protocol", RFC 8881,
DOI 10.17487/RFC8881, August 2020, DOI 10.17487/RFC8881, August 2020,
<https://www.rfc-editor.org/info/rfc8881>. <https://www.rfc-editor.org/info/rfc8881>.
Appendix A. Acknowledgments Acknowledgments
Trond Myklebust, Tom Haynes, and David Flynn all worked on the Trond Myklebust, Tom Haynes, and David Flynn all worked on the
prototype at Hammerspace. prototype at Hammerspace.
Dave Noveck, Chuck Lever, Rick Macklem, and Zaheduzzaman Sarker Dave Noveck, Chuck Lever, Rick Macklem, and Zaheduzzaman Sarker
provided reviews of the document. provided reviews of the document.
Jeff Layton provided experience from an implementation he authored. Jeff Layton provided experience from an implementation he authored.
Authors' Addresses Authors' Addresses
 End of changes. 70 change blocks. 
225 lines changed or deleted 268 lines changed or added

This html diff was produced by rfcdiff 1.48.