draft-ietf-nfsv4-minorversion2-17.txt   draft-ietf-nfsv4-minorversion2-18.txt 
NFSv4 T. Haynes, Ed. NFSv4 T. Haynes, Ed.
Internet-Draft NetApp Internet-Draft NetApp
Intended status: Standards Track November 27, 2012 Intended status: Standards Track March 13, 2013
Expires: May 31, 2013 Expires: September 14, 2013
NFS Version 4 Minor Version 2 NFS Version 4 Minor Version 2
draft-ietf-nfsv4-minorversion2-17.txt draft-ietf-nfsv4-minorversion2-18.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, Application I/O Advise, Space Reservations, Sparse Files, Copy, Application I/O Advise, Space Reservations, Sparse Files,
Application Data Blocks, and Labeled NFS. Application Data Blocks, and Labeled NFS.
skipping to change at page 1, line 41 skipping to change at page 1, line 41
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 May 31, 2013. This Internet-Draft will expire on September 14, 2013.
Copyright Notice Copyright Notice
Copyright (c) 2012 IETF Trust and the persons identified as the Copyright (c) 2013 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
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
skipping to change at page 2, line 29 skipping to change at page 2, line 29
1.4.1. Server-side Copy . . . . . . . . . . . . . . . . . . . 6 1.4.1. Server-side Copy . . . . . . . . . . . . . . . . . . . 6
1.4.2. Application I/O Advise . . . . . . . . . . . . . . . . 6 1.4.2. Application I/O Advise . . . . . . . . . . . . . . . . 6
1.4.3. Sparse Files . . . . . . . . . . . . . . . . . . . . . 6 1.4.3. Sparse Files . . . . . . . . . . . . . . . . . . . . . 6
1.4.4. Space Reservation . . . . . . . . . . . . . . . . . . 6 1.4.4. Space Reservation . . . . . . . . . . . . . . . . . . 6
1.4.5. Application Data Hole (ADH) Support . . . . . . . . . 6 1.4.5. Application Data Hole (ADH) Support . . . . . . . . . 6
1.4.6. Labeled NFS . . . . . . . . . . . . . . . . . . . . . 6 1.4.6. Labeled NFS . . . . . . . . . . . . . . . . . . . . . 6
1.5. Differences from NFSv4.1 . . . . . . . . . . . . . . . . 7 1.5. Differences from NFSv4.1 . . . . . . . . . . . . . . . . 7
2. Minor Versioning . . . . . . . . . . . . . . . . . . . . . . . 7 2. Minor Versioning . . . . . . . . . . . . . . . . . . . . . . . 7
3. Server-side Copy . . . . . . . . . . . . . . . . . . . . . . . 10 3. Server-side Copy . . . . . . . . . . . . . . . . . . . . . . . 10
3.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 10 3.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 10
3.2. Protocol Overview . . . . . . . . . . . . . . . . . . . . 11 3.2. Protocol Overview . . . . . . . . . . . . . . . . . . . . 10
3.2.1. Overview of Copy Operations . . . . . . . . . . . . . 11 3.2.1. Overview of Copy Operations . . . . . . . . . . . . . 11
3.2.2. Locking the Files . . . . . . . . . . . . . . . . . . 12 3.2.2. Locking the Files . . . . . . . . . . . . . . . . . . 12
3.2.3. Intra-Server Copy . . . . . . . . . . . . . . . . . . 12 3.2.3. Intra-Server Copy . . . . . . . . . . . . . . . . . . 12
3.2.4. Inter-Server Copy . . . . . . . . . . . . . . . . . . 14 3.2.4. Inter-Server Copy . . . . . . . . . . . . . . . . . . 14
3.2.5. Server-to-Server Copy Protocol . . . . . . . . . . . . 18 3.2.5. Server-to-Server Copy Protocol . . . . . . . . . . . . 17
3.3. Requirements for Operations . . . . . . . . . . . . . . . 19 3.3. Requirements for Operations . . . . . . . . . . . . . . . 18
3.3.1. netloc4 - Network Locations . . . . . . . . . . . . . 20 3.3.1. netloc4 - Network Locations . . . . . . . . . . . . . 19
3.3.2. Copy Offload Stateids . . . . . . . . . . . . . . . . 20 3.3.2. Offload Stateids . . . . . . . . . . . . . . . . . . . 19
3.4. Security Considerations . . . . . . . . . . . . . . . . . 21 3.4. Security Considerations . . . . . . . . . . . . . . . . . 20
3.4.1. Inter-Server Copy Security . . . . . . . . . . . . . . 21 3.4.1. Inter-Server Copy Security . . . . . . . . . . . . . . 20
4. Support for Application IO Hints . . . . . . . . . . . . . . . 29 4. Support for Application IO Hints . . . . . . . . . . . . . . . 28
5. Sparse Files . . . . . . . . . . . . . . . . . . . . . . . . . 29 5. Sparse Files . . . . . . . . . . . . . . . . . . . . . . . . . 28
5.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 29 5.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 28
5.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 30 5.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 29
5.3. New Operations . . . . . . . . . . . . . . . . . . . . . 30 5.3. New Operations . . . . . . . . . . . . . . . . . . . . . 29
5.3.1. READ_PLUS . . . . . . . . . . . . . . . . . . . . . . 31 5.3.1. READ_PLUS . . . . . . . . . . . . . . . . . . . . . . 30
5.3.2. WRITE_PLUS . . . . . . . . . . . . . . . . . . . . . . 31 5.3.2. WRITE_PLUS . . . . . . . . . . . . . . . . . . . . . . 30
6. Space Reservation . . . . . . . . . . . . . . . . . . . . . . 31 6. Space Reservation . . . . . . . . . . . . . . . . . . . . . . 30
6.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 31 6.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 30
7. Application Data Hole Support . . . . . . . . . . . . . . . . 33 7. Application Data Hole Support . . . . . . . . . . . . . . . . 32
7.1. Generic Framework . . . . . . . . . . . . . . . . . . . . 34 7.1. Generic Framework . . . . . . . . . . . . . . . . . . . . 33
7.1.1. Data Hole Representation . . . . . . . . . . . . . . . 35 7.1.1. Data Hole Representation . . . . . . . . . . . . . . . 34
7.1.2. Data Content . . . . . . . . . . . . . . . . . . . . . 35 7.1.2. Data Content . . . . . . . . . . . . . . . . . . . . . 34
7.2. An Example of Detecting Corruption . . . . . . . . . . . 36 7.2. An Example of Detecting Corruption . . . . . . . . . . . 35
7.3. Example of READ_PLUS . . . . . . . . . . . . . . . . . . 37 7.3. Example of READ_PLUS . . . . . . . . . . . . . . . . . . 36
8. Labeled NFS . . . . . . . . . . . . . . . . . . . . . . . . . 38 8. Labeled NFS . . . . . . . . . . . . . . . . . . . . . . . . . 37
8.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 38 8.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 37
8.2. Definitions . . . . . . . . . . . . . . . . . . . . . . . 39 8.2. Definitions . . . . . . . . . . . . . . . . . . . . . . . 38
8.3. MAC Security Attribute . . . . . . . . . . . . . . . . . 39 8.3. MAC Security Attribute . . . . . . . . . . . . . . . . . 38
8.3.1. Delegations . . . . . . . . . . . . . . . . . . . . . 40 8.3.1. Delegations . . . . . . . . . . . . . . . . . . . . . 39
8.3.2. Permission Checking . . . . . . . . . . . . . . . . . 40 8.3.2. Permission Checking . . . . . . . . . . . . . . . . . 39
8.3.3. Object Creation . . . . . . . . . . . . . . . . . . . 40 8.3.3. Object Creation . . . . . . . . . . . . . . . . . . . 39
8.3.4. Existing Objects . . . . . . . . . . . . . . . . . . . 41 8.3.4. Existing Objects . . . . . . . . . . . . . . . . . . . 40
8.3.5. Label Changes . . . . . . . . . . . . . . . . . . . . 41 8.3.5. Label Changes . . . . . . . . . . . . . . . . . . . . 40
8.4. pNFS Considerations . . . . . . . . . . . . . . . . . . . 41 8.4. pNFS Considerations . . . . . . . . . . . . . . . . . . . 40
8.5. Discovery of Server Labeled NFS Support . . . . . . . . . 42 8.5. Discovery of Server Labeled NFS Support . . . . . . . . . 41
8.6. MAC Security NFS Modes of Operation . . . . . . . . . . . 42 8.6. MAC Security NFS Modes of Operation . . . . . . . . . . . 41
8.6.1. Full Mode . . . . . . . . . . . . . . . . . . . . . . 42 8.6.1. Full Mode . . . . . . . . . . . . . . . . . . . . . . 41
8.6.2. Guest Mode . . . . . . . . . . . . . . . . . . . . . . 44 8.6.2. Guest Mode . . . . . . . . . . . . . . . . . . . . . . 43
8.7. Security Considerations . . . . . . . . . . . . . . . . . 44 8.7. Security Considerations . . . . . . . . . . . . . . . . . 43
9. Sharing change attribute implementation details with NFSv4 9. Sharing change attribute implementation details with NFSv4
clients . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 clients . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
9.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 45 9.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 44
10. Security Considerations . . . . . . . . . . . . . . . . . . . 45 10. Security Considerations . . . . . . . . . . . . . . . . . . . 44
11. Error Values . . . . . . . . . . . . . . . . . . . . . . . . . 45 11. Error Values . . . . . . . . . . . . . . . . . . . . . . . . . 44
11.1. Error Definitions . . . . . . . . . . . . . . . . . . . . 46 11.1. Error Definitions . . . . . . . . . . . . . . . . . . . . 45
11.1.1. General Errors . . . . . . . . . . . . . . . . . . . . 46 11.1.1. General Errors . . . . . . . . . . . . . . . . . . . . 45
11.1.2. Server to Server Copy Errors . . . . . . . . . . . . . 46 11.1.2. Server to Server Copy Errors . . . . . . . . . . . . . 45
11.1.3. Labeled NFS Errors . . . . . . . . . . . . . . . . . . 47 11.1.3. Labeled NFS Errors . . . . . . . . . . . . . . . . . . 46
11.2. New Operations and Their Valid Errors . . . . . . . . . . 47 11.2. New Operations and Their Valid Errors . . . . . . . . . . 46
11.3. New Callback Operations and Their Valid Errors . . . . . 50 11.3. New Callback Operations and Their Valid Errors . . . . . 49
12. New File Attributes . . . . . . . . . . . . . . . . . . . . . 51 12. New File Attributes . . . . . . . . . . . . . . . . . . . . . 50
12.1. New RECOMMENDED Attributes - List and Definition 12.1. New RECOMMENDED Attributes - List and Definition
References . . . . . . . . . . . . . . . . . . . . . . . 51 References . . . . . . . . . . . . . . . . . . . . . . . 50
12.2. Attribute Definitions . . . . . . . . . . . . . . . . . . 52 12.2. Attribute Definitions . . . . . . . . . . . . . . . . . . 51
13. Operations: REQUIRED, RECOMMENDED, or OPTIONAL . . . . . . . . 55 13. Operations: REQUIRED, RECOMMENDED, or OPTIONAL . . . . . . . . 54
14. NFSv4.2 Operations . . . . . . . . . . . . . . . . . . . . . . 59 14. NFSv4.2 Operations . . . . . . . . . . . . . . . . . . . . . . 58
14.1. Operation 59: COPY - Initiate a server-side copy . . . . 59 14.1. Operation 59: COPY - Initiate a server-side copy . . . . 58
14.2. Operation 60: OFFLOAD_ABORT - Cancel a server-side 14.2. Operation 60: OFFLOAD_ABORT - Cancel a server-side
copy . . . . . . . . . . . . . . . . . . . . . . . . . . 65 copy . . . . . . . . . . . . . . . . . . . . . . . . . . 64
14.3. Operation 61: COPY_NOTIFY - Notify a source server of 14.3. Operation 61: COPY_NOTIFY - Notify a source server of
a future copy . . . . . . . . . . . . . . . . . . . . . . 66 a future copy . . . . . . . . . . . . . . . . . . . . . . 65
14.4. Operation 62: OFFLOAD_REVOKE - Revoke a destination 14.4. Operation 62: OFFLOAD_REVOKE - Revoke a destination
server's copy privileges . . . . . . . . . . . . . . . . 68 server's copy privileges . . . . . . . . . . . . . . . . 67
14.5. Operation 63: OFFLOAD_STATUS - Poll for status of a 14.5. Operation 63: OFFLOAD_STATUS - Poll for status of a
server-side copy . . . . . . . . . . . . . . . . . . . . 69 server-side copy . . . . . . . . . . . . . . . . . . . . 68
14.6. Modification to Operation 42: EXCHANGE_ID - 14.6. Modification to Operation 42: EXCHANGE_ID -
Instantiate Client ID . . . . . . . . . . . . . . . . . . 70 Instantiate Client ID . . . . . . . . . . . . . . . . . . 69
14.7. Operation 64: WRITE_PLUS . . . . . . . . . . . . . . . . 71 14.7. Operation 64: WRITE_PLUS . . . . . . . . . . . . . . . . 70
14.8. Operation 67: IO_ADVISE - Application I/O access 14.8. Operation 67: IO_ADVISE - Application I/O access
pattern hints . . . . . . . . . . . . . . . . . . . . . . 76 pattern hints . . . . . . . . . . . . . . . . . . . . . . 75
14.9. Changes to Operation 51: LAYOUTRETURN . . . . . . . . . . 82 14.9. Changes to Operation 51: LAYOUTRETURN . . . . . . . . . . 81
14.10. Operation 65: READ_PLUS . . . . . . . . . . . . . . . . . 85 14.10. Operation 65: READ_PLUS . . . . . . . . . . . . . . . . . 84
14.11. Operation 66: SEEK . . . . . . . . . . . . . . . . . . . 90 14.11. Operation 66: SEEK . . . . . . . . . . . . . . . . . . . 89
15. NFSv4.2 Callback Operations . . . . . . . . . . . . . . . . . 91 15. NFSv4.2 Callback Operations . . . . . . . . . . . . . . . . . 90
15.1. Operation 15: CB_OFFLOAD - Report results of an 15.1. Operation 15: CB_OFFLOAD - Report results of an
asynchronous operation . . . . . . . . . . . . . . . . . 91 asynchronous operation . . . . . . . . . . . . . . . . . 90
16. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 92 16. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 91
17. References . . . . . . . . . . . . . . . . . . . . . . . . . . 93 17. References . . . . . . . . . . . . . . . . . . . . . . . . . . 92
17.1. Normative References . . . . . . . . . . . . . . . . . . 93 17.1. Normative References . . . . . . . . . . . . . . . . . . 92
17.2. Informative References . . . . . . . . . . . . . . . . . 93 17.2. Informative References . . . . . . . . . . . . . . . . . 92
Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 94 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 94
Appendix B. RFC Editor Notes . . . . . . . . . . . . . . . . . . 95 Appendix B. RFC Editor Notes . . . . . . . . . . . . . . . . . . 94
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 96 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 95
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 [9] and the second minor version, version, NFSv4.0, is described in [9] and the second minor version,
NFSv4.1, is described in [1]. It follows the guidelines for minor NFSv4.1, is described in [1]. It follows the guidelines for minor
versioning that are listed in Section 11 of [9]. versioning that are listed in Section 11 of [9].
skipping to change at page 9, line 35 skipping to change at page 9, line 35
the request as an XDR decode error. This approach allows for the request as an XDR decode error. This approach allows for
the obsolescence of an operation while maintaining its structure the obsolescence of an operation while maintaining its structure
so that a future minor version can reintroduce the operation. so that a future minor version can reintroduce the operation.
1. Minor versions may declare that an attribute MUST NOT be 1. Minor versions may declare that an attribute MUST NOT be
implemented. implemented.
2. Minor versions may declare that a flag bit or enumeration 2. Minor versions may declare that a flag bit or enumeration
value MUST NOT be implemented. value MUST NOT be implemented.
10. Minor versions may declare an operation to be OBSOLESCENT, which 10. Minor versions may declare an operation to be DEPRECATED, which
indicates an intention to remove the operation (i.e., make it indicates the plan to remove the operation in the next release.
MANDATORY TO NOT implement) in a subsequent minor version. Such Such a labeling does not effect whether the operation is
labeling is separate from the question of whether the operation REQUIRED or RECOMMENDED or OPTIONAL. I.e., an operation may be
is REQUIRED or RECOMMENDED or OPTIONAL in the current minor both REQUIRED for the given minor version and earmarked for MUST
version. An operation may be both REQUIRED for the given minor NOT be implemented for the next release. Note that this two
version and marked OBSOLESCENT, with the expectation that it minor version release approach is put in place to mitigate
will be MANDATORY TO NOT implement in the next (or other design and implementation mistakes. As such, even if an
subsequent) minor version. operation is marked DEPRECATED in a given minor release, it may
end up not being marked as MUST NOT implement in the next minor
11. Note that the early notification of operation obsolescence is version.
put in place to mitigate the effects of design and
implementation mistakes, and to allow protocol development to
adapt to unexpected changes in the pace of implementation. Even
if an operation is marked OBSOLESCENT in a given minor version,
it may end up not being marked MANDATORY TO NOT implement in the
next minor version. In unusual circumstances, it might not be
marked OBSOLESCENT in a subsequent minor version, and never
become MANDATORY TO NOT implement.
12. Minor versions may downgrade features from REQUIRED to 11. Minor versions may downgrade features (i.e., operations and
RECOMMENDED, from RECOMMENDED to OPTIONAL, or from OPIONAL to attributes) from REQUIRED to RECOMMENDED, or RECOMMENDED to
MANDATORY TO NOT implement. Also, if a feature was marked as OPTIONAL. Also, if a feature was marked as DEPRECATED in a
OBSOLESCENT in the prior minor version, it may be downgraded prior minor version, it may be downgraded from REQUIRED to
from REQUIRED to OPTIONAL from RECOMMENDED to MANDATORY TO NOT OPTIONAL.
implement, or from REQUIRED to MANDATORY TO NOT implement.
13. Minor versions may upgrade features from OPTIONAL to 12. Minor versions may upgrade features from OPTIONAL to
RECOMMENDED, or RECOMMENDED to REQUIRED. Also, if a feature was RECOMMENDED, or RECOMMENDED to REQUIRED.
marked as OBSOLESCENT in the prior minor version, it may be
upgraded to not be OBSOLESCENT.
14. A client and server that support minor version X SHOULD support 13. A client and server that support minor version X SHOULD support
minor versions 0 through X-1 as well. minor versions 0 through X-1 as well.
15. Except for infrastructural changes, a minor version must not 14. Except for infrastructural changes, a minor version must not
introduce REQUIRED new features. introduce REQUIRED new features.
This rule allows for the introduction of new functionality and This rule allows for the introduction of new functionality and
forces the use of implementation experience before designating a forces the use of implementation experience before designating a
feature as REQUIRED. On the other hand, some classes of feature as REQUIRED. On the other hand, some classes of
features are infrastructural and have broad effects. Allowing features are infrastructural and have broad effects. Allowing
infrastructural features to be RECOMMENDED or OPTIONAL infrastructural features to be RECOMMENDED or OPTIONAL
complicates implementation of the minor version. complicates implementation of the minor version.
16. A client MUST NOT attempt to use a stateid, filehandle, or 15. A client MUST NOT attempt to use a stateid, filehandle, or
similar returned object from the COMPOUND procedure with minor similar returned object from the COMPOUND procedure with minor
version X for another COMPOUND procedure with minor version Y, version X for another COMPOUND procedure with minor version Y,
where X != Y. where X != Y.
3. Server-side Copy 3. Server-side Copy
3.1. Introduction 3.1. Introduction
The server-side copy feature provides a mechanism for the NFS client The server-side copy feature provides a mechanism for the NFS client
to perform a file copy on the server without the data being to perform a file copy on the server without the data being
skipping to change at page 20, line 39 skipping to change at page 19, line 39
UTF-8 string. If the netloc4 is of type NL4_NETADDR, the nl_addr UTF-8 string. If the netloc4 is of type NL4_NETADDR, the nl_addr
field MUST contain a valid netaddr4 as defined in Section 3.3.9 of field MUST contain a valid netaddr4 as defined in Section 3.3.9 of
[1]. [1].
When netloc4 values are used for an inter-server copy as shown in When netloc4 values are used for an inter-server copy as shown in
Figure 3, their values may be evaluated on the source server, Figure 3, their values may be evaluated on the source server,
destination server, and client. The network environment in which destination server, and client. The network environment in which
these systems operate should be configured so that the netloc4 values these systems operate should be configured so that the netloc4 values
are interpreted as intended on each system. are interpreted as intended on each system.
3.3.2. Copy Offload Stateids 3.3.2. Offload Stateids
A server may perform a copy offload operation asynchronously. An A server may perform a copy offload operation asynchronously. An
asynchronous copy is tracked using a copy offload stateid. Copy asynchronous copy is tracked using a offload stateid. Copy offload
offload stateids are included in the COPY, OFFLOAD_ABORT, stateids are included in the COPY, OFFLOAD_ABORT, OFFLOAD_STATUS, and
OFFLOAD_STATUS, and CB_OFFLOAD operations. CB_OFFLOAD operations.
Section 8.2.4 of [1] specifies that stateids are valid until either Section 8.2.4 of [1] specifies that stateids are valid until either
(A) the client or server restart or (B) the client returns the (A) the client or server restart or (B) the client returns the
resource. resource.
A copy offload stateid will be valid until either (A) the client or A offload stateid will be valid until either (A) the client or server
server restarts or (B) the client returns the resource by issuing a restarts or (B) the client returns the resource by issuing a
OFFLOAD_ABORT operation or the client replies to a CB_OFFLOAD OFFLOAD_ABORT operation or the client replies to a CB_OFFLOAD
operation. operation.
A copy offload stateid's seqid MUST NOT be 0. In the context of a A offload stateid's seqid MUST NOT be 0. In the context of a copy
copy offload operation, it is ambiguous to indicate the most recent offload operation, it is ambiguous to indicate the most recent copy
copy offload operation using a stateid with seqid of 0. Therefore a offload operation using a stateid with seqid of 0. Therefore a copy
copy offload stateid with seqid of 0 MUST be considered invalid. offload stateid with seqid of 0 MUST be considered invalid.
3.4. Security Considerations 3.4. Security Considerations
The security considerations pertaining to NFSv4 [9] apply to this The security considerations pertaining to NFSv4 [9] apply to this
chapter. chapter.
The standard security mechanisms provide by NFSv4 [9] may be used to The standard security mechanisms provide by NFSv4 [9] may be used to
secure the protocol described in this chapter. secure the protocol described in this chapter.
NFSv4 clients and servers supporting the inter-server copy operations NFSv4 clients and servers supporting the inter-server copy operations
skipping to change at page 31, line 6 skipping to change at page 30, line 6
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.
5.3. New Operations 5.3. New Operations
READ_PLUS and WRITE_PLUS are new variants of the NFSv4.1 READ and READ_PLUS and WRITE_PLUS are new variants of the NFSv4.1 READ and
WRITE operations [1]. Besides being able to support all of the data WRITE operations [1]. Besides being able to support all of the data
semantics of those operations, they can also be used by the client semantics of those operations, they can also be used by the client
and server to efficiently transfer both holes and ADHs (see and server to efficiently transfer both holes and ADHs (see
Section 7.1.1). As both READ and WRITE are inefficient for transfer Section 7.1.1). As both READ and WRITE are inefficient for transfer
of sparse sections of the file, they are marked as END-OF-LIFE in of sparse sections of the file, they are marked as OBSOLESCENT in
NFSv4.2. Instead, a client should utilize READ_PLUS and WRITE_PLUS. NFSv4.2. Instead, a client should utilize READ_PLUS and WRITE_PLUS.
Note that as the client has no a priori knowledge of whether either Note that as the client has no a priori knowledge of whether either
an ADH or a hole is present or not, if it supports these operations an ADH or a hole is present or not, if it supports these operations
and so does the server, then it should always use these operations. and so does the server, then it should always use these operations.
5.3.1. READ_PLUS 5.3.1. READ_PLUS
For holes, READ_PLUS extends the response to avoid returning data for For holes, READ_PLUS extends the response to avoid returning data for
portions of the file which are either initialized and contain no portions of the file which are initialized and contain no backing
backing store or if the result would appear to be so. I.e., if the store. Additionally it will do so if the result would appear to be a
result was a data block composed entirely of zeros, then it is easier hole. I.e., if the result was a data block composed entirely of
to return a hole. Returning data blocks of uninitialized data wastes zeros, then it is easier to return a hole. Returning data blocks of
computational and network resources, thus reducing performance. For uninitialized data wastes computational and network resources, thus
ADHs, READ_PLUS is used to return the metadata describing the reducing performance. For ADHs, READ_PLUS is used to return the
portions of the file which are either initialized and contain no metadata describing the portions of the file which are initialized
backing store. and contain no backing store.
If the client sends a READ operation, it is explicitly stating that If the client sends a READ operation, it is explicitly stating that
it is neither supporting sparse files nor ADHs. So if a READ occurs it is neither supporting sparse files nor ADHs. So if a READ occurs
on a sparse ADH or file, then the server must expand such data to be on a sparse ADH or file, then the server must expand such data to be
raw bytes. If a READ occurs in the middle of a hole or ADH, the raw bytes. If a READ occurs in the middle of a hole or ADH, the
server can only send back bytes starting from that offset. In server can only send back bytes starting from that offset. In
contrast, if a READ_PLUS occurs in the middle of a hole or ADH, the contrast, if a READ_PLUS occurs in the middle of a hole or ADH, the
server can send back a range which starts before the offset and server can send back a range which starts before the offset and
extends past the range. extends past the range.
skipping to change at page 38, line 36 skipping to change at page 37, line 36
Access control on these attributes are done through a combination of Access control on these attributes are done through a combination of
two mechanisms. As with other recommended attributes on file objects two mechanisms. As with other recommended attributes on file objects
the usual DAC checks (ACLs and permission bits) will be performed to the usual DAC checks (ACLs and permission bits) will be performed to
ensure that proper file ownership is enforced. In addition a MAC ensure that proper file ownership is enforced. In addition a MAC
system MAY be employed on the client, server, or both to enforce system MAY be employed on the client, server, or both to enforce
additional policy on what subjects may modify security label additional policy on what subjects may modify security label
information. information.
The second change is to provide methods for the client to determine The second change is to provide methods for the client to determine
if the security label has changed. A client which needs to know if a if the security label has changed. A client which needs to know if a
label is going to change SHOULD register a delegation on that file. label is going to change SHOULD request a delegation on that file.
In order to change the security label, the server will have to recall In order to change the security label, the server will have to recall
all delegations. This will inform the client of the change. If a all delegations. This will inform the client of the change. If a
client wants to detect if the label has changed, it MAY use VERIFY client wants to detect if the label has changed, it MAY use VERIFY
and NVERIFY on FATTR4_CHANGE_SEC_LABEL to detect that the and NVERIFY on FATTR4_CHANGE_SEC_LABEL to detect that the
FATTR4_SEC_LABEL has been modified. FATTR4_SEC_LABEL has been modified.
The final change necessary is a modification to the RPC layer used in The final change necessary is a modification to the RPC layer used in
NFSv4 in the form of a new version of the RPCSEC_GSS [6] framework. NFSv4 in the form of a new version of the RPCSEC_GSS [6] framework.
In order for an NFSv4 server to apply MAC checks it must obtain In order for an NFSv4 server to apply MAC checks it must obtain
additional information from the client. Several methods were additional information from the client. Several methods were
skipping to change at page 55, line 36 skipping to change at page 54, line 36
12.2.5. Attribute 78: space_freed 12.2.5. Attribute 78: space_freed
space_freed gives the number of bytes freed if the file is deleted. space_freed gives the number of bytes freed if the file is deleted.
This attribute is read only and is of type length4. It is a per file This attribute is read only and is of type length4. It is a per file
attribute. attribute.
13. Operations: REQUIRED, RECOMMENDED, or OPTIONAL 13. Operations: REQUIRED, RECOMMENDED, or OPTIONAL
The following tables summarize the operations of the NFSv4.2 protocol The following tables summarize the operations of the NFSv4.2 protocol
and the corresponding designation of REQUIRED, RECOMMENDED, and and the corresponding designation of REQUIRED, RECOMMENDED, and
OPTIONAL to implement or either END-OF-LIFE or MUST NOT implement. OPTIONAL to implement or either OBSOLESCENT or MUST NOT implement.
The designation of END-OF_LIFE is reserved for those operations which The designation of OBSOLESCENT for those operations which are defined
are defined in either NFSv4.0 or NFSv4.1 and are intended to be in either NFSv4.0 or NFSv4.1 and are intended to be classified as
classified as MUST NOT be implemented in NFSv4.3. The designation of MUST NOT be implemented in NFSv4.3. The designation of MUST NOT
MUST NOT implement is reserved for those operations that were defined implement is reserved for those operations that were defined in
in either NFSv4.0 or NFSV4.1 and MUST NOT be implemented in NFSv4.2. either NFSv4.0 or NFSV4.1 and MUST NOT be implemented in NFSv4.2.
For the most part, the REQUIRED, RECOMMENDED, or OPTIONAL designation For the most part, the REQUIRED, RECOMMENDED, or OPTIONAL designation
for operations sent by the client is for the server implementation. for operations sent by the client is for the server implementation.
The client is generally required to implement the operations needed The client is generally required to implement the operations needed
for the operating environment for which it serves. For example, a for the operating environment for which it serves. For example, a
read-only NFSv4.2 client would have no need to implement the WRITE read-only NFSv4.2 client would have no need to implement the WRITE
operation and is not required to do so. operation and is not required to do so.
The REQUIRED or OPTIONAL designation for callback operations sent by The REQUIRED or OPTIONAL designation for callback operations sent by
the server is for both the client and server. Generally, the client the server is for both the client and server. Generally, the client
skipping to change at page 73, line 18 skipping to change at page 72, line 18
as per the NFSv4.1 WRITE operation results. If wr_callback_id is as per the NFSv4.1 WRITE operation results. If wr_callback_id is
set, it indicates an asynchronous reply (see Section 14.7.3.4). set, it indicates an asynchronous reply (see Section 14.7.3.4).
WRITE_PLUS has to support all of the errors which are returned by WRITE_PLUS has to support all of the errors which are returned by
WRITE plus NFS4ERR_UNION_NOTSUPP. If the client asks for a hole and WRITE plus NFS4ERR_UNION_NOTSUPP. If the client asks for a hole and
the server does not support that arm of the discriminated union, but the server does not support that arm of the discriminated union, but
does support one or more additional arms, it can signal to the client does support one or more additional arms, it can signal to the client
that it supports the operation, but not the arm with that it supports the operation, but not the arm with
NFS4ERR_UNION_NOTSUPP. NFS4ERR_UNION_NOTSUPP.
If the client supports WRITE_PLUS, it MUST support CB_OFFLOAD. If the client supports WRITE_PLUS and any arm of the discriminated
union other than NFS4_CONTENT_DATA, it MUST support CB_OFFLOAD.
14.7.3.1. Data 14.7.3.1. Data
The d_offset specifies the offset where the data should be written. The d_offset specifies the offset where the data should be written.
An d_offset of zero specifies that the write should start at the An d_offset of zero specifies that the write should start at the
beginning of the file. The d_count, as encoded as part of the opaque beginning of the file. The d_count, as encoded as part of the opaque
data parameter, represents the number of bytes of data that are to be data parameter, represents the number of bytes of data that are to be
written. If the d_count is zero, the WRITE_PLUS will succeed and written. If the d_count is zero, the WRITE_PLUS will succeed and
return a d_count of zero subject to permissions checking. return a d_count of zero subject to permissions checking.
Note that d_allocated has no meaning for WRITE_PLUS. Note that d_allocated has no meaning for WRITE_PLUS.
The data MUST be written synchronously and MUST follow the same
semantics of COMMIT as does the WRITE operation.
14.7.3.2. Hole punching 14.7.3.2. Hole punching
Whenever a client wishes to zero the blocks backing a particular Whenever a client wishes to zero the blocks backing a particular
region in the file, it calls the WRITE_PLUS operation with the region in the file, it calls the WRITE_PLUS operation with the
current filehandle set to the filehandle of the file in question, and current filehandle set to the filehandle of the file in question, and
the equivalent of start offset and length in bytes of the region set the equivalent of start offset and length in bytes of the region set
in wpa_hole.di_offset and wpa_hole.di_length respectively. If the in wpa_hole.di_offset and wpa_hole.di_length respectively. If the
wpa_hole.di_allocated is set to TRUE, then the blocks will be zeroed wpa_hole.di_allocated is set to TRUE, then the blocks will be zeroed
and if it is set to FALSE, then they will be deallocated. All and if it is set to FALSE, then they will be deallocated. All
further reads to this region MUST return zeros until overwritten. further reads to this region MUST return zeros until overwritten.
skipping to change at page 75, line 35 skipping to change at page 74, line 42
determining to service the operation asynchronously. If it decides determining to service the operation asynchronously. If it decides
to do so, it sets the stateid in wr_callback_id to be that of the to do so, it sets the stateid in wr_callback_id to be that of the
wp_stateid. If it does not set the wr_callback_id, then the result wp_stateid. If it does not set the wr_callback_id, then the result
is synchronous. is synchronous.
When the client determines that the reply will be given When the client determines that the reply will be given
asynchronously, it should not assume anything about the contents of asynchronously, it should not assume anything about the contents of
what it wrote until it is informed by the server that the operation what it wrote until it is informed by the server that the operation
is complete. It can use OFFLOAD_STATUS (Section 14.5) to monitor the is complete. It can use OFFLOAD_STATUS (Section 14.5) to monitor the
operation and OFFLOAD_ABORT (Section 14.2) to cancel the operation. operation and OFFLOAD_ABORT (Section 14.2) to cancel the operation.
An example of a asynchronous WRITE_PLUS is shown in Figure 6. An example of a asynchronous WRITE_PLUS is shown in Figure 6. Note
that as with the COPY operation, WRITE_PLUS must provide a stateid
for tracking the asynchronous operation.
Client Server Client Server
+ + + +
| | | |
|--- OPEN ---------------------------->| Client opens |--- OPEN ---------------------------->| Client opens
|<------------------------------------/| the file |<------------------------------------/| the file
| | | |
|--- WRITE_PLUS ---------------------->| Client punches |--- WRITE_PLUS ---------------------->| Client punches
|<------------------------------------/| a hole |<------------------------------------/| a hole
| | | |
skipping to change at page 76, line 36 skipping to change at page 75, line 36
|<------------------------------------/| the file |<------------------------------------/| the file
| | | |
| | | |
Figure 6: An asynchronous WRITE_PLUS. Figure 6: An asynchronous WRITE_PLUS.
When CB_OFFLOAD informs the client of the successful WRITE_PLUS, the When CB_OFFLOAD informs the client of the successful WRITE_PLUS, the
write_response4 embedded in the operation will provide the necessary write_response4 embedded in the operation will provide the necessary
information that a synchronous WRITE_PLUS would have provided. information that a synchronous WRITE_PLUS would have provided.
Regardelss of whether the operation is asynchronous or synchronous,
it MUST still support the COMMIT operation semantics as outlined in
Section 18.3 of [1]. I.e., COMMIT works on one or more WRITE
operations and the WRITE_PLUS operation can appear as several WRITE
operations to the server. The client can use locking operations to
control the behavior on the server with respect to a long running
asynchornous write operations.
14.8. Operation 67: IO_ADVISE - Application I/O access pattern hints 14.8. Operation 67: IO_ADVISE - Application I/O access pattern hints
14.8.1. ARGUMENT 14.8.1. ARGUMENT
enum IO_ADVISE_type4 { enum IO_ADVISE_type4 {
IO_ADVISE4_NORMAL = 0, IO_ADVISE4_NORMAL = 0,
IO_ADVISE4_SEQUENTIAL = 1, IO_ADVISE4_SEQUENTIAL = 1,
IO_ADVISE4_SEQUENTIAL_BACKWARDS = 2, IO_ADVISE4_SEQUENTIAL_BACKWARDS = 2,
IO_ADVISE4_RANDOM = 3, IO_ADVISE4_RANDOM = 3,
IO_ADVISE4_WILLNEED = 4, IO_ADVISE4_WILLNEED = 4,
IO_ADVISE4_WILLNEED_OPPORTUNISTIC = 5, IO_ADVISE4_WILLNEED_OPPORTUNISTIC = 5,
skipping to change at page 78, line 13 skipping to change at page 77, line 13
the advice. the advice.
The following are the allowed hints for a stateid holder: The following are the allowed hints for a stateid holder:
IO_ADVISE4_NORMAL There is no advice to give, this is the default IO_ADVISE4_NORMAL There is no advice to give, this is the default
behavior. behavior.
IO_ADVISE4_SEQUENTIAL Expects to access the specified data IO_ADVISE4_SEQUENTIAL Expects to access the specified data
sequentially from lower offsets to higher offsets. sequentially from lower offsets to higher offsets.
IO_ADVISE4_SEQUENTIAL BACKWARDS Expects to access the specified data IO_ADVISE4_SEQUENTIAL_BACKWARDS Expects to access the specified data
sequentially from higher offsets to lower offsets. sequentially from higher offsets to lower offsets.
IO_ADVISE4_RANDOM Expects to access the specified data in a random IO_ADVISE4_RANDOM Expects to access the specified data in a random
order. order.
IO_ADVISE4_WILLNEED Expects to access the specified data in the near IO_ADVISE4_WILLNEED Expects to access the specified data in the near
future. future.
IO_ADVISE4_WILLNEED_OPPORTUNISTIC Expects to possibly access the IO_ADVISE4_WILLNEED_OPPORTUNISTIC Expects to possibly access the
data in the near future. This is a speculative hint, and data in the near future. This is a speculative hint, and
skipping to change at page 92, line 22 skipping to change at page 91, line 22
CB_OFFLOAD is used to report to the client the results of an CB_OFFLOAD is used to report to the client the results of an
asynchronous operation, e.g., Server-side Copy or a hole punch. The asynchronous operation, e.g., Server-side Copy or a hole punch. The
coa_fh and coa_stateid identify the transaction and the coa_status coa_fh and coa_stateid identify the transaction and the coa_status
indicates success or failure. The coa_resok4.wr_callback_id MUST NOT indicates success or failure. The coa_resok4.wr_callback_id MUST NOT
be set. If the transaction failed, then the coa_bytes_copied be set. If the transaction failed, then the coa_bytes_copied
contains the number of bytes copied before the failure occurred. The contains the number of bytes copied before the failure occurred. The
coa_bytes_copied value indicates the number of bytes copied but not coa_bytes_copied value indicates the number of bytes copied but not
which specific bytes have been copied. which specific bytes have been copied.
If the client supports either the COPY or WRITE_PLUS operation, the If the client supports either
client is REQUIRED to support the CB_OFFLOAD operation.
1. the COPY operation
2. the WRITE_PLUS operation and any arm of the discriminated union
other than NFS4_CONTENT_DATA
then the client is REQUIRED to support the CB_OFFLOAD operation.
There is a potential race between the reply to the original There is a potential race between the reply to the original
transaction on the forechannel and the CB_OFFLOAD callback on the transaction on the forechannel and the CB_OFFLOAD callback on the
backchannel. Sections 2.10.6.3 and 20.9.3 in [1] describes how to backchannel. Sections 2.10.6.3 and 20.9.3 in [1] describes how to
handle this type of issue. handle this type of issue.
15.1.3.1. Server-side Copy 15.1.3.1. Server-side Copy
CB_OFFLOAD is used for both intra- and inter-server asynchronous CB_OFFLOAD is used for both intra- and inter-server asynchronous
copies. This operation is sent by the destination server to the copies. This operation is sent by the destination server to the
skipping to change at page 93, line 4 skipping to change at page 92, line 6
CB_OFFLOAD is used to report the completion of either a hole punch or CB_OFFLOAD is used to report the completion of either a hole punch or
an ADH initialization. Upon success, the coa_resok4 will contain the an ADH initialization. Upon success, the coa_resok4 will contain the
same information that a synchronous WRITE_PLUS would have returned. same information that a synchronous WRITE_PLUS would have returned.
16. IANA Considerations 16. IANA Considerations
This section uses terms that are defined in [24]. This section uses terms that are defined in [24].
17. References 17. References
17.1. Normative References 17.1. Normative References
[1] Shepler, S., Eisler, M., and D. Noveck, "Network File System [1] Shepler, S., Eisler, M., and D. Noveck, "Network File System
(NFS) Version 4 Minor Version 1 Protocol", RFC 5661, (NFS) Version 4 Minor Version 1 Protocol", RFC 5661,
January 2010. January 2010.
[2] Haynes, T., "Network File System (NFS) Version 4 Minor Version [2] Haynes, T., "Network File System (NFS) Version 4 Minor Version
2 External Data Representation Standard (XDR) Description", 2 External Data Representation Standard (XDR) Description",
March 2011. March 2013.
[3] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [3] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986,
January 2005. January 2005.
[4] Haynes, T. and N. Williams, "Remote Procedure Call (RPC) [4] Haynes, T. and N. Williams, "Remote Procedure Call (RPC)
Security Version 3", draft-williams-rpcsecgssv3 (work in Security Version 3", draft-williams-rpcsecgssv3 (work in
progress), 2011. progress), 2011.
[5] The Open Group, "Section 'posix_fadvise()' of System Interfaces [5] The Open Group, "Section 'posix_fadvise()' of System Interfaces
skipping to change at page 93, line 38 skipping to change at page 92, line 41
[7] Halevy, B., Welch, B., and J. Zelenka, "Object-Based Parallel [7] Halevy, B., Welch, B., and J. Zelenka, "Object-Based Parallel
NFS (pNFS) Operations", RFC 5664, January 2010. NFS (pNFS) Operations", RFC 5664, January 2010.
17.2. Informative References 17.2. Informative References
[8] Bradner, S., "Key words for use in RFCs to Indicate Requirement [8] Bradner, S., "Key words for use in RFCs to Indicate Requirement
Levels", March 1997. Levels", March 1997.
[9] Haynes, T. and D. Noveck, "Network File System (NFS) version 4 [9] Haynes, T. and D. Noveck, "Network File System (NFS) version 4
Protocol", draft-ietf-nfsv4-rfc3530bis-20 (Work In Progress), Protocol", draft-ietf-nfsv4-rfc3530bis-25 (Work In Progress),
October 2012. February 2013.
[10] Lentini, J., Everhart, C., Ellard, D., Tewari, R., and M. Naik, [10] Lentini, J., Everhart, C., Ellard, D., Tewari, R., and M. Naik,
"NSDB Protocol for Federated Filesystems", "NSDB Protocol for Federated Filesystems",
draft-ietf-nfsv4-federated-fs-protocol (Work In Progress), draft-ietf-nfsv4-federated-fs-protocol (Work In Progress),
2010. 2010.
[11] Lentini, J., Everhart, C., Ellard, D., Tewari, R., and M. Naik, [11] Lentini, J., Everhart, C., Ellard, D., Tewari, R., and M. Naik,
"Administration Protocol for Federated Filesystems", "Administration Protocol for Federated Filesystems",
draft-ietf-nfsv4-federated-fs-admin (Work In Progress), 2010. draft-ietf-nfsv4-federated-fs-admin (Work In Progress), 2010.
skipping to change at page 95, line 38 skipping to change at page 94, line 43
early reviewers included Benny Halevy and Pranoop Erasani. early reviewers 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,
Stephen Smalley, Sorrin Faibish, Nico Williams, and David Black also Stephen Smalley, Sorrin Faibish, Nico Williams, and David Black also
contributed in the final push to get this accepted. contributed in the final push to get this accepted.
During the review process, Talia Reyes-Ortiz helped the sessions run During the review process, Talia Reyes-Ortiz helped the sessions run
smoothly. While many people contributed here and there, the core smoothly. While many people contributed here and there, the core
reviewers were Andy Adamson, Pranoop Erasani, Bruce Fields, Chuck reviewers were Andy Adamson, Pranoop Erasani, Bruce Fields, Chuck
Lever, Trond Myklebust, David Noveck, and Peter Staubach. Lever, Trond Myklebust, David Noveck, Peter Staubach, and Mike
Kupfer.
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. 40 change blocks. 
143 lines changed or deleted 154 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/