draft-ietf-nfsv4-minorversion2-08.txt   draft-ietf-nfsv4-minorversion2-09.txt 
NFSv4 T. Haynes NFSv4 T. Haynes
Internet-Draft Editor Internet-Draft Editor
Intended status: Standards Track April 25, 2012 Intended status: Standards Track May 02, 2012
Expires: October 27, 2012 Expires: November 3, 2012
NFS Version 4 Minor Version 2 NFS Version 4 Minor Version 2
draft-ietf-nfsv4-minorversion2-08.txt draft-ietf-nfsv4-minorversion2-09.txt
Abstract Abstract
This Internet-Draft describes NFS version 4 minor version two, This Internet-Draft describes NFS version 4 minor version two,
focusing mainly on the protocol extensions made from NFS version 4 focusing mainly on the protocol extensions made from NFS version 4
minor version 0 and NFS version 4 minor version 1. Major extensions minor version 0 and NFS version 4 minor version 1. Major extensions
introduced in NFS version 4 minor version two include: Server-side introduced in NFS version 4 minor version two include: Server-side
Copy, Space Reservations, and Support for Sparse Files. Copy, Space Reservations, and Support for Sparse Files.
Requirements Language Requirements Language
skipping to change at page 1, line 40 skipping to change at page 1, line 40
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on October 27, 2012. This Internet-Draft will expire on November 3, 2012.
Copyright Notice Copyright Notice
Copyright (c) 2012 IETF Trust and the persons identified as the Copyright (c) 2012 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 Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 3, line 29 skipping to change at page 3, line 29
2.2.2. Inter-Server Copy . . . . . . . . . . . . . . . . . . 11 2.2.2. Inter-Server Copy . . . . . . . . . . . . . . . . . . 11
2.2.3. Server-to-Server Copy Protocol . . . . . . . . . . . . 13 2.2.3. Server-to-Server Copy Protocol . . . . . . . . . . . . 13
2.3. Operations . . . . . . . . . . . . . . . . . . . . . . . 15 2.3. Operations . . . . . . . . . . . . . . . . . . . . . . . 15
2.3.1. netloc4 - Network Locations . . . . . . . . . . . . . 15 2.3.1. netloc4 - Network Locations . . . . . . . . . . . . . 15
2.3.2. Copy Offload Stateids . . . . . . . . . . . . . . . . 16 2.3.2. Copy Offload Stateids . . . . . . . . . . . . . . . . 16
2.4. Security Considerations . . . . . . . . . . . . . . . . . 16 2.4. Security Considerations . . . . . . . . . . . . . . . . . 16
2.4.1. Inter-Server Copy Security . . . . . . . . . . . . . . 16 2.4.1. Inter-Server Copy Security . . . . . . . . . . . . . . 16
3. Sparse Files . . . . . . . . . . . . . . . . . . . . . . . . . 25 3. Sparse Files . . . . . . . . . . . . . . . . . . . . . . . . . 25
3.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 25 3.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 25
3.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 25 3.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 25
3.3. Determining the next hole/data . . . . . . . . . . . . . 26
4. Space Reservation . . . . . . . . . . . . . . . . . . . . . . 26 4. Space Reservation . . . . . . . . . . . . . . . . . . . . . . 26
4.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 26 4.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 26
5. Support for Application IO Hints . . . . . . . . . . . . . . . 28 5. Support for Application IO Hints . . . . . . . . . . . . . . . 28
5.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 28 5.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 28
5.2. POSIX Requirements . . . . . . . . . . . . . . . . . . . 29 5.2. POSIX Requirements . . . . . . . . . . . . . . . . . . . 29
5.3. Additional Requirements . . . . . . . . . . . . . . . . . 30 5.3. Additional Requirements . . . . . . . . . . . . . . . . . 30
5.4. Security Considerations . . . . . . . . . . . . . . . . . 31 5.4. Security Considerations . . . . . . . . . . . . . . . . . 31
5.5. IANA Considerations . . . . . . . . . . . . . . . . . . . 31 5.5. IANA Considerations . . . . . . . . . . . . . . . . . . . 31
6. Application Data Block Support . . . . . . . . . . . . . . . . 31 6. Application Data Block Support . . . . . . . . . . . . . . . . 31
6.1. Generic Framework . . . . . . . . . . . . . . . . . . . . 32 6.1. Generic Framework . . . . . . . . . . . . . . . . . . . . 32
skipping to change at page 4, line 4 skipping to change at page 3, line 52
6.3. An Example of Detecting Corruption . . . . . . . . . . . 34 6.3. An Example of Detecting Corruption . . . . . . . . . . . 34
6.4. Example of READ_PLUS . . . . . . . . . . . . . . . . . . 35 6.4. Example of READ_PLUS . . . . . . . . . . . . . . . . . . 35
6.5. Zero Filled Holes . . . . . . . . . . . . . . . . . . . . 36 6.5. Zero Filled Holes . . . . . . . . . . . . . . . . . . . . 36
7. Labeled NFS . . . . . . . . . . . . . . . . . . . . . . . . . 36 7. Labeled NFS . . . . . . . . . . . . . . . . . . . . . . . . . 36
7.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 36 7.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 36
7.2. Definitions . . . . . . . . . . . . . . . . . . . . . . . 37 7.2. Definitions . . . . . . . . . . . . . . . . . . . . . . . 37
7.3. MAC Security Attribute . . . . . . . . . . . . . . . . . 37 7.3. MAC Security Attribute . . . . . . . . . . . . . . . . . 37
7.3.1. Interpreting FATTR4_SEC_LABEL . . . . . . . . . . . . 38 7.3.1. Interpreting FATTR4_SEC_LABEL . . . . . . . . . . . . 38
7.3.2. Delegations . . . . . . . . . . . . . . . . . . . . . 39 7.3.2. Delegations . . . . . . . . . . . . . . . . . . . . . 39
7.3.3. Permission Checking . . . . . . . . . . . . . . . . . 39 7.3.3. Permission Checking . . . . . . . . . . . . . . . . . 39
7.3.4. Object Creation . . . . . . . . . . . . . . . . . . . 40 7.3.4. Object Creation . . . . . . . . . . . . . . . . . . . 39
7.3.5. Existing Objects . . . . . . . . . . . . . . . . . . . 40 7.3.5. Existing Objects . . . . . . . . . . . . . . . . . . . 40
7.3.6. Label Changes . . . . . . . . . . . . . . . . . . . . 40 7.3.6. Label Changes . . . . . . . . . . . . . . . . . . . . 40
7.4. pNFS Considerations . . . . . . . . . . . . . . . . . . . 41 7.4. pNFS Considerations . . . . . . . . . . . . . . . . . . . 41
7.5. Discovery of Server LNFS Support . . . . . . . . . . . . 41 7.5. Discovery of Server LNFS Support . . . . . . . . . . . . 41
7.6. MAC Security NFS Modes of Operation . . . . . . . . . . . 42 7.6. MAC Security NFS Modes of Operation . . . . . . . . . . . 41
7.6.1. Full Mode . . . . . . . . . . . . . . . . . . . . . . 42 7.6.1. Full Mode . . . . . . . . . . . . . . . . . . . . . . 42
7.6.2. Guest Mode . . . . . . . . . . . . . . . . . . . . . . 43 7.6.2. Guest Mode . . . . . . . . . . . . . . . . . . . . . . 43
7.7. Security Considerations . . . . . . . . . . . . . . . . . 44 7.7. Security Considerations . . . . . . . . . . . . . . . . . 43
8. Sharing change attribute implementation details with NFSv4 8. Sharing change attribute implementation details with NFSv4
clients . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 clients . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
8.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 44 8.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 44
8.2. Definition of the 'change_attr_type' per-file system 8.2. Definition of the 'change_attr_type' per-file system
attribute . . . . . . . . . . . . . . . . . . . . . . . . 45 attribute . . . . . . . . . . . . . . . . . . . . . . . . 44
9. Security Considerations . . . . . . . . . . . . . . . . . . . 46 9. Security Considerations . . . . . . . . . . . . . . . . . . . 46
10. Error Values . . . . . . . . . . . . . . . . . . . . . . . . . 46 10. Error Values . . . . . . . . . . . . . . . . . . . . . . . . . 46
10.1. Error Definitions . . . . . . . . . . . . . . . . . . . . 46 10.1. Error Definitions . . . . . . . . . . . . . . . . . . . . 46
10.1.1. General Errors . . . . . . . . . . . . . . . . . . . . 47 10.1.1. General Errors . . . . . . . . . . . . . . . . . . . . 46
10.1.2. Server to Server Copy Errors . . . . . . . . . . . . . 47 10.1.2. Server to Server Copy Errors . . . . . . . . . . . . . 46
10.1.3. Labeled NFS Errors . . . . . . . . . . . . . . . . . . 47 10.1.3. Labeled NFS Errors . . . . . . . . . . . . . . . . . . 47
11. File Attributes . . . . . . . . . . . . . . . . . . . . . . . 48 11. File Attributes . . . . . . . . . . . . . . . . . . . . . . . 47
11.1. Attribute Definitions . . . . . . . . . . . . . . . . . . 48 11.1. Attribute Definitions . . . . . . . . . . . . . . . . . . 47
12. Operations: REQUIRED, RECOMMENDED, or OPTIONAL . . . . . . . . 48 12. Operations: REQUIRED, RECOMMENDED, or OPTIONAL . . . . . . . . 48
13. NFSv4.2 Operations . . . . . . . . . . . . . . . . . . . . . . 52 13. NFSv4.2 Operations . . . . . . . . . . . . . . . . . . . . . . 52
13.1. Operation 59: COPY - Initiate a server-side copy . . . . 52 13.1. Operation 59: COPY - Initiate a server-side copy . . . . 52
13.2. Operation 60: COPY_ABORT - Cancel a server-side copy . . 59 13.2. Operation 60: COPY_ABORT - Cancel a server-side copy . . 59
13.3. Operation 61: COPY_NOTIFY - Notify a source server of 13.3. Operation 61: COPY_NOTIFY - Notify a source server of
a future copy . . . . . . . . . . . . . . . . . . . . . . 61 a future copy . . . . . . . . . . . . . . . . . . . . . . 60
13.4. Operation 62: COPY_REVOKE - Revoke a destination 13.4. Operation 62: COPY_REVOKE - Revoke a destination
server's copy privileges . . . . . . . . . . . . . . . . 63 server's copy privileges . . . . . . . . . . . . . . . . 62
13.5. Operation 63: COPY_STATUS - Poll for status of a 13.5. Operation 63: COPY_STATUS - Poll for status of a
server-side copy . . . . . . . . . . . . . . . . . . . . 64 server-side copy . . . . . . . . . . . . . . . . . . . . 63
13.6. Modification to Operation 42: EXCHANGE_ID - 13.6. Modification to Operation 42: EXCHANGE_ID -
Instantiate Client ID . . . . . . . . . . . . . . . . . . 65 Instantiate Client ID . . . . . . . . . . . . . . . . . . 64
13.7. Operation 64: INITIALIZE . . . . . . . . . . . . . . . . 66 13.7. Operation 64: INITIALIZE . . . . . . . . . . . . . . . . 65
13.8. Operation 67: IO_ADVISE - Application I/O access 13.8. Operation 67: IO_ADVISE - Application I/O access
pattern hints . . . . . . . . . . . . . . . . . . . . . . 70 pattern hints . . . . . . . . . . . . . . . . . . . . . . 69
13.9. Changes to Operation 51: LAYOUTRETURN . . . . . . . . . . 76 13.9. Changes to Operation 51: LAYOUTRETURN . . . . . . . . . . 75
13.10. Operation 65: READ_PLUS . . . . . . . . . . . . . . . . . 79 13.10. Operation 65: READ_PLUS . . . . . . . . . . . . . . . . . 78
13.11. Operation 66: SEEK . . . . . . . . . . . . . . . . . . . 85 13.11. Operation 66: SEEK . . . . . . . . . . . . . . . . . . . 83
14. NFSv4.2 Callback Operations . . . . . . . . . . . . . . . . . 86 14. NFSv4.2 Callback Operations . . . . . . . . . . . . . . . . . 84
14.1. Procedure 16: CB_ATTR_CHANGED - Notify Client that 14.1. Procedure 16: CB_ATTR_CHANGED - Notify Client that
the File's Attributes Changed . . . . . . . . . . . . . . 86 the File's Attributes Changed . . . . . . . . . . . . . . 84
14.2. Operation 15: CB_COPY - Report results of a 14.2. Operation 15: CB_COPY - Report results of a
server-side copy . . . . . . . . . . . . . . . . . . . . 87 server-side copy . . . . . . . . . . . . . . . . . . . . 85
15. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 88 15. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 87
16. References . . . . . . . . . . . . . . . . . . . . . . . . . . 88 16. References . . . . . . . . . . . . . . . . . . . . . . . . . . 87
16.1. Normative References . . . . . . . . . . . . . . . . . . 88 16.1. Normative References . . . . . . . . . . . . . . . . . . 87
16.2. Informative References . . . . . . . . . . . . . . . . . 89 16.2. Informative References . . . . . . . . . . . . . . . . . 88
Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 90
Appendix B. RFC Editor Notes . . . . . . . . . . . . . . . . . . 91 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 89
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 91 Appendix B. RFC Editor Notes . . . . . . . . . . . . . . . . . . 90
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 90
1. Introduction 1. Introduction
1.1. The NFS Version 4 Minor Version 2 Protocol 1.1. The NFS Version 4 Minor Version 2 Protocol
The NFS version 4 minor version 2 (NFSv4.2) protocol is the third The NFS version 4 minor version 2 (NFSv4.2) protocol is the third
minor version of the NFS version 4 (NFSv4) protocol. The first minor minor version of the NFS version 4 (NFSv4) protocol. The first minor
version, NFSv4.0, is described in [10] and the second minor version, version, NFSv4.0, is described in [10] and the second minor version,
NFSv4.1, is described in [2]. It follows the guidelines for minor NFSv4.1, is described in [2]. It follows the guidelines for minor
versioning that are listed in Section 11 of [10]. versioning that are listed in Section 11 of [10].
skipping to change at page 18, line 37 skipping to change at page 18, line 37
struct copy_from_auth_priv { struct copy_from_auth_priv {
secret4 cfap_shared_secret; secret4 cfap_shared_secret;
netloc4 cfap_destination; netloc4 cfap_destination;
/* the NFSv4 user name that the user principal maps to */ /* the NFSv4 user name that the user principal maps to */
utf8str_mixed cfap_username; utf8str_mixed cfap_username;
/* equal to seq_num of rpc_gss_cred_vers_3_t */ /* equal to seq_num of rpc_gss_cred_vers_3_t */
unsigned int cfap_seq_num; unsigned int cfap_seq_num;
}; };
cap_shared_secret is a secret value the user principal generates. cfp_shared_secret is a secret value the user principal generates.
copy_to_auth: A user principal is authorizing a destination copy_to_auth: A user principal is authorizing a destination
principal ("nfs@<destination>") to allow it to copy a file from principal ("nfs@<destination>") to allow it to copy a file from
the source to the destination. This privilege is established on the source to the destination. This privilege is established on
the destination server before the user principal sends a COPY the destination server before the user principal sends a COPY
operation to the destination server. operation to the destination server.
struct copy_to_auth_priv { struct copy_to_auth_priv {
/* equal to cfap_shared_secret */ /* equal to cfap_shared_secret */
secret4 ctap_shared_secret; secret4 ctap_shared_secret;
skipping to change at page 26, line 10 skipping to change at page 26, line 10
Hole: A byte range within a Sparse file that contains regions of all Hole: A byte range within a Sparse file that contains regions of all
zeroes. For block-based file systems, this could also be an zeroes. For block-based file systems, this could also be an
unallocated region of the file. unallocated region of the file.
Hole Threshold: The minimum length of a Hole as determined by the Hole Threshold: The minimum length of a Hole as determined by the
server. If a server chooses to define a Hole Threshold, then it server. If a server chooses to define a Hole Threshold, then it
would not return hole information about holes with a length would not return hole information about holes with a length
shorter than the Hole Threshold. shorter than the Hole Threshold.
3.3. Determining the next hole/data
Solaris and ZFS support an extension to lseek(2) that allows
applications to discover holes in a file. The values, SEEK_HOLE and
SEEK_DATA, allow clients to seek to the next hole or beginning of
data, respectively.
4. Space Reservation 4. Space Reservation
4.1. Introduction 4.1. Introduction
This section describes a set of operations that allow applications This section describes a set of operations that allow applications
such as hypervisors to reserve space for a file, report the amount of such as hypervisors to reserve space for a file, report the amount of
actual disk space a file occupies and freeup the backing space of a actual disk space a file occupies and freeup the backing space of a
file when it is not required. In virtualized environments, virtual file when it is not required. In virtualized environments, virtual
disk files are often stored on NFS mounted volumes. Since virtual disk files are often stored on NFS mounted volumes. Since virtual
disk files represent the hard disks of virtual machines, hypervisors disk files represent the hard disks of virtual machines, hypervisors
skipping to change at page 46, line 40 skipping to change at page 46, line 25
entered in the reply and the Compound request will be terminated. entered in the reply and the Compound request will be terminated.
10.1. Error Definitions 10.1. Error Definitions
Protocol Error Definitions Protocol Error Definitions
+--------------------------+--------+------------------+ +--------------------------+--------+------------------+
| Error | Number | Description | | Error | Number | Description |
+--------------------------+--------+------------------+ +--------------------------+--------+------------------+
| NFS4ERR_BADLABEL | 10093 | Section 10.1.3.1 | | NFS4ERR_BADLABEL | 10093 | Section 10.1.3.1 |
| NFS4ERR_MAC_ACCESS | 10094 | Section 10.1.3.2 |
| NFS4ERR_METADATA_NOTSUPP | 10090 | Section 10.1.2.1 | | NFS4ERR_METADATA_NOTSUPP | 10090 | Section 10.1.2.1 |
| NFS4ERR_OFFLOAD_DENIED | 10091 | Section 10.1.2.2 | | NFS4ERR_OFFLOAD_DENIED | 10091 | Section 10.1.2.2 |
| NFS4ERR_PARTNER_NO_AUTH | 10089 | Section 10.1.2.3 | | NFS4ERR_PARTNER_NO_AUTH | 10089 | Section 10.1.2.3 |
| NFS4ERR_PARTNER_NOTSUPP | 10088 | Section 10.1.2.4 | | NFS4ERR_PARTNER_NOTSUPP | 10088 | Section 10.1.2.4 |
| NFS4ERR_UNION_NOTSUPP | 10095 | Section 10.1.1.1 | | NFS4ERR_UNION_NOTSUPP | 10094 | Section 10.1.1.1 |
| NFS4ERR_WRONG_LFS | 10092 | Section 10.1.3.3 | | NFS4ERR_WRONG_LFS | 10092 | Section 10.1.3.2 |
+--------------------------+--------+------------------+ +--------------------------+--------+------------------+
Table 1 Table 1
10.1.1. General Errors 10.1.1. General Errors
This section deals with errors that are applicable to a broad set of This section deals with errors that are applicable to a broad set of
different purposes. different purposes.
10.1.1.1. NFS4ERR_UNION_NOTSUPP (Error Code 10095) 10.1.1.1. NFS4ERR_UNION_NOTSUPP (Error Code 10094)
One of the arguments to the operation is a discriminated union and One of the arguments to the operation is a discriminated union and
while the server supports the given operation, it does not support while the server supports the given operation, it does not support
the selected arm of the discriminated union. For an example, see the selected arm of the discriminated union. For an example, see
READ_PLUS (Section 13.10). READ_PLUS (Section 13.10).
10.1.2. Server to Server Copy Errors 10.1.2. Server to Server Copy Errors
These errors deal with the interaction between server to server These errors deal with the interaction between server to server
copies. copies.
skipping to change at page 48, line 4 skipping to change at page 47, line 35
10.1.2.4. NFS4ERR_PARTNER_NOTSUPP (Error Code 10088) 10.1.2.4. NFS4ERR_PARTNER_NOTSUPP (Error Code 10088)
The remote server does not support the server-to-server copy offload The remote server does not support the server-to-server copy offload
protocol. protocol.
10.1.3. Labeled NFS Errors 10.1.3. Labeled NFS Errors
These errors are used in LNFS. These errors are used in LNFS.
10.1.3.1. NFS4ERR_BADLABEL (Error Code 10093) 10.1.3.1. NFS4ERR_BADLABEL (Error Code 10093)
10.1.3.2. NFS4ERR_MAC_ACCESS (Error Code 10094)
10.1.3.3. NFS4ERR_WRONG_LFS (Error Code 10092) The label specified is invalid in some manner.
10.1.3.2. NFS4ERR_WRONG_LFS (Error Code 10092)
The LFS specified in the subject label is not compatible with the LFS
in object label.
11. File Attributes 11. File Attributes
11.1. Attribute Definitions 11.1. Attribute Definitions
11.1.1. Attribute 77: space_reserved 11.1.1. Attribute 77: space_reserved
The space_reserve attribute is a read/write attribute of type The space_reserve attribute is a read/write attribute of type
boolean. It is a per file attribute. When the space_reserved boolean. It is a per file attribute. When the space_reserved
attribute is set via SETATTR, the server must ensure that there is attribute is set via SETATTR, the server must ensure that there is
skipping to change at page 49, line 29 skipping to change at page 49, line 15
on the fore channel that will be a catalyst for the server sending on the fore channel that will be a catalyst for the server sending
callback operations. A partial exception is CB_RECALL_SLOT; the only callback operations. A partial exception is CB_RECALL_SLOT; the only
way the client can avoid supporting this operation is by not creating way the client can avoid supporting this operation is by not creating
a backchannel. a backchannel.
Since this is a summary of the operations and their designation, Since this is a summary of the operations and their designation,
there are subtleties that are not presented here. Therefore, if there are subtleties that are not presented here. Therefore, if
there is a question of the requirements of implementation, the there is a question of the requirements of implementation, the
operation descriptions themselves must be consulted along with other operation descriptions themselves must be consulted along with other
relevant explanatory text within this either specification or that of relevant explanatory text within this either specification or that of
NFSv4.1 [2].. NFSv4.1 [2].
The abbreviations used in the second and third columns of the table The abbreviations used in the second and third columns of the table
are defined as follows. are defined as follows.
REQ REQUIRED to implement REQ REQUIRED to implement
REC RECOMMEND to implement REC RECOMMEND to implement
OPT OPTIONAL to implement OPT OPTIONAL to implement
skipping to change at page 73, line 23 skipping to change at page 72, line 23
range. range.
Clients should assume that hints included in an IO_ADVISE operation Clients should assume that hints included in an IO_ADVISE operation
will be forgotten once the file is closed. will be forgotten once the file is closed.
13.8.4. IMPLEMENTATION 13.8.4. IMPLEMENTATION
The NFS client may choose to issue an IO_ADVISE operation to the The NFS client may choose to issue an IO_ADVISE operation to the
server in several different instances. server in several different instances.
The most obvious is in direct response to an applications execution The most obvious is in direct response to an application's execution
of posix_fadvise. In this case, IO_ADVISE4_WRITE and IO_ADVISE4_READ of posix_fadvise. In this case, IO_ADVISE4_WRITE and IO_ADVISE4_READ
may be set based upon the type of file access specified when the file may be set based upon the type of file access specified when the file
was opened. was opened.
Another useful point would be when an application indicates it is Another useful point would be when an application indicates it is
using direct I/O. Direct I/O may be specified at file open, in which using direct I/O. Direct I/O may be specified at file open, in which
case a IO_ADVISE may be included in the same compound as the OPEN case a IO_ADVISE may be included in the same compound as the OPEN
operation with the IO_ADVISE4_NOREUSE flag set. Direct I/O may also operation with the IO_ADVISE4_NOREUSE flag set. Direct I/O may also
be specified separately, in which case a IO_ADVISE operation can be be specified separately, in which case a IO_ADVISE operation can be
sent to the server separately. As above, IO_ADVISE4_WRITE and sent to the server separately. As above, IO_ADVISE4_WRITE and
skipping to change at page 82, line 9 skipping to change at page 81, line 9
di_length returned must be for the entire hole. This result is di_length returned must be for the entire hole. This result is
considered valid until the file is changed (detected via the change considered valid until the file is changed (detected via the change
attribute). The server MUST provide the same semantics for the hole attribute). The server MUST provide the same semantics for the hole
as if the client read the region and received zeroes; the implied as if the client read the region and received zeroes; the implied
holes contents lifetime MUST be exactly the same as any other read holes contents lifetime MUST be exactly the same as any other read
data. data.
If the client specifies an rpa_offset and rpa_count value that begins If the client specifies an rpa_offset and rpa_count value that begins
in a non-hole of the file but extends into hole the server should in a non-hole of the file but extends into hole the server should
return an array comprised of both data and a hole. The client MUST return an array comprised of both data and a hole. The client MUST
be prepared for the server to reurn a short read describing just the be prepared for the server to return a short read describing just the
data. The client will then issue another READ_PLUS for the remaining data. The client will then issue another READ_PLUS for the remaining
bytes, which the server will respond with information about the hole bytes, which the server will respond with information about the hole
in the file. in the file.
Except when special stateids are used, the stateid value for a Except when special stateids are used, the stateid value for a
READ_PLUS request represents a value returned from a previous byte- READ_PLUS request represents a value returned from a previous byte-
range lock or share reservation request or the stateid associated range lock or share reservation request or the stateid associated
with a delegation. The stateid identifies the associated owners if with a delegation. The stateid identifies the associated owners if
any and is used by the server to verify that the associated locks are any and is used by the server to verify that the associated locks are
still valid (e.g., have not been revoked). still valid (e.g., have not been revoked).
skipping to change at page 82, line 45 skipping to change at page 81, line 45
server MAY allow the READ_PLUS to be serviced subject to mandatory server MAY allow the READ_PLUS to be serviced subject to mandatory
byte-range locks or the current share deny modes for the file. For a byte-range locks or the current share deny modes for the file. For a
READ_PLUS with a stateid value of all bits equal to one, the server READ_PLUS with a stateid value of all bits equal to one, the server
MAY allow READ_PLUS operations to bypass locking checks at the MAY allow READ_PLUS operations to bypass locking checks at the
server. server.
On success, the current filehandle retains its value. On success, the current filehandle retains its value.
13.10.4. IMPLEMENTATION 13.10.4. IMPLEMENTATION
If the server returns a short read, then the client should send In general, the IMPLEMENTATION notes for READ in Section 18.22.4 of
another READ_PLUS to get the remaining data. A server may return [2] also apply to READ_PLUS. One delta is that when the owner has a
less data than requested under several circumstances. The file may locked byte range, the server MUST return an array of rpr_contents
have been truncated by another client or perhaps on the server with values inside that range.
itself, changing the file size from what the requesting client
believes to be the case. This would reduce the actual amount of data
available to the client. It is possible that the server reduced the
transfer size and so return a short read result. Server resource
exhaustion may also occur in a short read.
If mandatory byte-range locking is in effect for the file, and if the
byte-range corresponding to the data to be read from the file is
WRITE_LT locked by an owner not associated with the stateid, the
server will return the NFS4ERR_LOCKED error. The client should try
to get the appropriate READ_LT via the LOCK operation before re-
attempting the READ_PLUS. When the READ_PLUS completes, the client
should release the byte-range lock via LOCKU. In addition, the
server MUST return an array of rpr_contents with values of that are
within the owner's locked byte range.
If another client has an OPEN_DELEGATE_WRITE delegation for the file
being read, the delegation must be recalled, and the operation cannot
proceed until that delegation is returned or revoked. Except where
this happens very quickly, one or more NFS4ERR_DELAY errors will be
returned to requests made while the delegation remains outstanding.
Normally, delegations will not be recalled as a result of a READ_PLUS
operation since the recall will occur as a result of an earlier OPEN.
However, since it is possible for a READ_PLUS to be done with a
special stateid, the server needs to check for this case even though
the client should have done an OPEN previously.
13.10.4.1. Additional pNFS Implementation Information 13.10.4.1. Additional pNFS Implementation Information
With pNFS, the semantics of using READ_PLUS remains the same. Any With pNFS, the semantics of using READ_PLUS remains the same. Any
data server MAY return a hole or ADB result for a READ_PLUS request data server MAY return a hole or ADB result for a READ_PLUS request
that it receives. that it receives.
When a data server chooses to return a hole result, it has the option When a data server chooses to return a hole result, it has the option
of returning hole information for the data stored on that data server of returning hole information for the data stored on that data server
(as defined by the data layout), but it MUST not return results for a (as defined by the data layout), but it MUST not return results for a
skipping to change at page 85, line 8 skipping to change at page 83, line 29
288K], hole[288K, 354K]>. Returns an array of the 32K data and 288K], hole[288K, 354K]>. Returns an array of the 32K data and
the hole which extends to 354K. the hole which extends to 354K.
4. READ_PLUS(s, 354K, 64K) --> NFS_OK, eof = true, <data[354K, 4. READ_PLUS(s, 354K, 64K) --> NFS_OK, eof = true, <data[354K,
418K]>. Returns the final 64K of data and informs the client 418K]>. Returns the final 64K of data and informs the client
there is no more data in the file. there is no more data in the file.
13.11. Operation 66: SEEK 13.11. Operation 66: SEEK
SEEK is an operation that allows a client to determine the location SEEK is an operation that allows a client to determine the location
of the next data_content4 in a file. of the next data_content4 in a file. It allows an implementation of
the emerging extension to lseek(2) to allow clients to determine
SEEK_HOLE and SEEK_DATA.
13.11.1. ARGUMENT 13.11.1. ARGUMENT
struct SEEK4args { struct SEEK4args {
/* CURRENT_FH: file */ /* CURRENT_FH: file */
stateid4 sa_stateid; stateid4 sa_stateid;
offset4 sa_offset; offset4 sa_offset;
data_content4 sa_what; data_content4 sa_what;
}; };
skipping to change at page 90, line 47 skipping to change at page 89, line 47
Hildebrand and Marc Eshel. Valuable input and advice was received Hildebrand and Marc Eshel. Valuable input and advice was received
from Sorin Faibish, Bruce Fields, Benny Halevy, Trond Myklebust, and from Sorin Faibish, Bruce Fields, Benny Halevy, Trond Myklebust, and
Richard Scheffenegger. Richard Scheffenegger.
For the Application IO Hints, the original draft was by Dean For the Application IO Hints, the original draft was by Dean
Hildebrand, Mike Eisler, Trond Myklebust, and Sam Falkner. Some Hildebrand, Mike Eisler, Trond Myklebust, and Sam Falkner. Some
early reviwers included Benny Halevy and Pranoop Erasani. early reviwers included Benny Halevy and Pranoop Erasani.
For Labeled NFS, the original draft was by David Quigley, James For Labeled NFS, the original draft was by David Quigley, James
Morris, Jarret Lu, and Tom Haynes. Peter Staubach, Trond Myklebust, Morris, Jarret Lu, and Tom Haynes. Peter Staubach, Trond Myklebust,
Sorrin Faibish, Nico Williams, and David Black also contributed in Stephen Smalley, Sorrin Faibish, Nico Williams, and David Black also
the final push to get this accepted. contributed in the final push to get this accepted.
Appendix B. RFC Editor Notes Appendix B. RFC Editor Notes
[RFC Editor: please remove this section prior to publishing this [RFC Editor: please remove this section prior to publishing this
document as an RFC] document as an RFC]
[RFC Editor: prior to publishing this document as an RFC, please [RFC Editor: prior to publishing this document as an RFC, please
replace all occurrences of RFCTBD10 with RFCxxxx where xxxx is the replace all occurrences of RFCTBD10 with RFCxxxx where xxxx is the
RFC number of this document] RFC number of this document]
 End of changes. 30 change blocks. 
82 lines changed or deleted 54 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/