draft-ietf-nfsv4-minorversion2-11.txt   draft-ietf-nfsv4-minorversion2-12.txt 
NFSv4 T. Haynes NFSv4 T. Haynes
Internet-Draft Editor Internet-Draft Editor
Intended status: Standards Track May 23, 2012 Intended status: Standards Track June 20, 2012
Expires: November 24, 2012 Expires: December 22, 2012
NFS Version 4 Minor Version 2 NFS Version 4 Minor Version 2
draft-ietf-nfsv4-minorversion2-11.txt draft-ietf-nfsv4-minorversion2-12.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 November 24, 2012. This Internet-Draft will expire on December 22, 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 18 skipping to change at page 3, line 18
1.1. The NFS Version 4 Minor Version 2 Protocol . . . . . . . 6 1.1. The NFS Version 4 Minor Version 2 Protocol . . . . . . . 6
1.2. Scope of This Document . . . . . . . . . . . . . . . . . 6 1.2. Scope of This Document . . . . . . . . . . . . . . . . . 6
1.3. NFSv4.2 Goals . . . . . . . . . . . . . . . . . . . . . . 6 1.3. NFSv4.2 Goals . . . . . . . . . . . . . . . . . . . . . . 6
1.4. Overview of NFSv4.2 Features . . . . . . . . . . . . . . 7 1.4. Overview of NFSv4.2 Features . . . . . . . . . . . . . . 7
1.4.1. Sparse Files . . . . . . . . . . . . . . . . . . . . . 7 1.4.1. Sparse Files . . . . . . . . . . . . . . . . . . . . . 7
1.4.2. Application I/O Advise . . . . . . . . . . . . . . . . 7 1.4.2. Application I/O Advise . . . . . . . . . . . . . . . . 7
1.5. Differences from NFSv4.1 . . . . . . . . . . . . . . . . 7 1.5. Differences from NFSv4.1 . . . . . . . . . . . . . . . . 7
2. NFS Server-side Copy . . . . . . . . . . . . . . . . . . . . . 7 2. NFS Server-side Copy . . . . . . . . . . . . . . . . . . . . . 7
2.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 7 2.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 7
2.2. Protocol Overview . . . . . . . . . . . . . . . . . . . . 8 2.2. Protocol Overview . . . . . . . . . . . . . . . . . . . . 8
2.2.1. Intra-Server Copy . . . . . . . . . . . . . . . . . . 10 2.2.1. Overview of Copy Operations . . . . . . . . . . . . . 9
2.2.2. Inter-Server Copy . . . . . . . . . . . . . . . . . . 11 2.2.2. Intra-Server Copy . . . . . . . . . . . . . . . . . . 9
2.2.3. Server-to-Server Copy Protocol . . . . . . . . . . . . 14 2.2.3. Inter-Server Copy . . . . . . . . . . . . . . . . . . 10
2.3. Operations . . . . . . . . . . . . . . . . . . . . . . . 16 2.2.4. Server-to-Server Copy Protocol . . . . . . . . . . . . 13
2.3.1. netloc4 - Network Locations . . . . . . . . . . . . . 16 2.3. Requirements for Operations . . . . . . . . . . . . . . . 15
2.3.2. Copy Offload Stateids . . . . . . . . . . . . . . . . 17 2.3.1. netloc4 - Network Locations . . . . . . . . . . . . . 15
2.3.2. Copy Offload Stateids . . . . . . . . . . . . . . . . 16
2.4. Security Considerations . . . . . . . . . . . . . . . . . 17 2.4. Security Considerations . . . . . . . . . . . . . . . . . 17
2.4.1. Inter-Server Copy Security . . . . . . . . . . . . . . 17 2.4.1. Inter-Server Copy Security . . . . . . . . . . . . . . 17
3. Support for Application IO Hints . . . . . . . . . . . . . . . 26 3. Support for Application IO Hints . . . . . . . . . . . . . . . 25
3.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 26 3.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 25
3.2. POSIX Requirements . . . . . . . . . . . . . . . . . . . 26 3.2. POSIX Requirements . . . . . . . . . . . . . . . . . . . 26
3.3. Additional Requirements . . . . . . . . . . . . . . . . . 27 3.3. Additional Requirements . . . . . . . . . . . . . . . . . 27
3.4. Security Considerations . . . . . . . . . . . . . . . . . 28 3.4. Security Considerations . . . . . . . . . . . . . . . . . 28
3.5. IANA Considerations . . . . . . . . . . . . . . . . . . . 28 3.5. IANA Considerations . . . . . . . . . . . . . . . . . . . 28
4. Sparse Files . . . . . . . . . . . . . . . . . . . . . . . . . 28 4. Sparse Files . . . . . . . . . . . . . . . . . . . . . . . . . 28
4.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 29 4.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 28
4.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 29 4.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 29
5. Space Reservation . . . . . . . . . . . . . . . . . . . . . . 30 5. Space Reservation . . . . . . . . . . . . . . . . . . . . . . 29
5.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 30 5.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 29
6. Application Data Block Support . . . . . . . . . . . . . . . . 32 6. Application Data Block Support . . . . . . . . . . . . . . . . 31
6.1. Generic Framework . . . . . . . . . . . . . . . . . . . . 33 6.1. Generic Framework . . . . . . . . . . . . . . . . . . . . 32
6.1.1. Data Block Representation . . . . . . . . . . . . . . 33 6.1.1. Data Block Representation . . . . . . . . . . . . . . 33
6.1.2. Data Content . . . . . . . . . . . . . . . . . . . . . 34 6.1.2. Data Content . . . . . . . . . . . . . . . . . . . . . 33
6.2. pNFS Considerations . . . . . . . . . . . . . . . . . . . 34 6.2. pNFS Considerations . . . . . . . . . . . . . . . . . . . 33
6.3. An Example of Detecting Corruption . . . . . . . . . . . 34 6.3. An Example of Detecting Corruption . . . . . . . . . . . 34
6.4. Example of READ_PLUS . . . . . . . . . . . . . . . . . . 36 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 . . . . . . . . . . . . . . . . . . . . . . 37 7.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 36
7.2. Definitions . . . . . . . . . . . . . . . . . . . . . . . 38 7.2. Definitions . . . . . . . . . . . . . . . . . . . . . . . 37
7.3. MAC Security Attribute . . . . . . . . . . . . . . . . . 38 7.3. MAC Security Attribute . . . . . . . . . . . . . . . . . 38
7.3.1. Delegations . . . . . . . . . . . . . . . . . . . . . 39 7.3.1. Delegations . . . . . . . . . . . . . . . . . . . . . 38
7.3.2. Permission Checking . . . . . . . . . . . . . . . . . 39 7.3.2. Permission Checking . . . . . . . . . . . . . . . . . 39
7.3.3. Object Creation . . . . . . . . . . . . . . . . . . . 39 7.3.3. Object Creation . . . . . . . . . . . . . . . . . . . 39
7.3.4. Existing Objects . . . . . . . . . . . . . . . . . . . 40 7.3.4. Existing Objects . . . . . . . . . . . . . . . . . . . 39
7.3.5. Label Changes . . . . . . . . . . . . . . . . . . . . 40 7.3.5. Label Changes . . . . . . . . . . . . . . . . . . . . 39
7.4. pNFS Considerations . . . . . . . . . . . . . . . . . . . 41 7.4. pNFS Considerations . . . . . . . . . . . . . . . . . . . 40
7.5. Discovery of Server Labeled NFS Support . . . . . . . . . 41 7.5. Discovery of Server Labeled NFS Support . . . . . . . . . 40
7.6. MAC Security NFS Modes of Operation . . . . . . . . . . . 41 7.6. MAC Security NFS Modes of Operation . . . . . . . . . . . 41
7.6.1. Full Mode . . . . . . . . . . . . . . . . . . . . . . 42 7.6.1. Full Mode . . . . . . . . . . . . . . . . . . . . . . 41
7.6.2. Guest Mode . . . . . . . . . . . . . . . . . . . . . . 43 7.6.2. Guest Mode . . . . . . . . . . . . . . . . . . . . . . 42
7.7. Security Considerations . . . . . . . . . . . . . . . . . 43 7.7. Security Considerations . . . . . . . . . . . . . . . . . 43
8. Sharing change attribute implementation details with NFSv4 8. Sharing change attribute implementation details with NFSv4
clients . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 clients . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
8.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 44 8.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 43
9. Security Considerations . . . . . . . . . . . . . . . . . . . 44 9. Security Considerations . . . . . . . . . . . . . . . . . . . 44
10. Error Values . . . . . . . . . . . . . . . . . . . . . . . . . 44 10. Error Values . . . . . . . . . . . . . . . . . . . . . . . . . 44
10.1. Error Definitions . . . . . . . . . . . . . . . . . . . . 45 10.1. Error Definitions . . . . . . . . . . . . . . . . . . . . 44
10.1.1. General Errors . . . . . . . . . . . . . . . . . . . . 45 10.1.1. General Errors . . . . . . . . . . . . . . . . . . . . 44
10.1.2. Server to Server Copy Errors . . . . . . . . . . . . . 45 10.1.2. Server to Server Copy Errors . . . . . . . . . . . . . 45
10.1.3. Labeled NFS Errors . . . . . . . . . . . . . . . . . . 46 10.1.3. Labeled NFS Errors . . . . . . . . . . . . . . . . . . 45
11. New File Attributes . . . . . . . . . . . . . . . . . . . . . 46 11. New File Attributes . . . . . . . . . . . . . . . . . . . . . 46
11.1. New RECOMMENDED Attributes - List and Definition 11.1. New RECOMMENDED Attributes - List and Definition
References . . . . . . . . . . . . . . . . . . . . . . . 46 References . . . . . . . . . . . . . . . . . . . . . . . 46
11.2. Attribute Definitions . . . . . . . . . . . . . . . . . . 47 11.2. Attribute Definitions . . . . . . . . . . . . . . . . . . 46
12. Operations: REQUIRED, RECOMMENDED, or OPTIONAL . . . . . . . . 50 12. Operations: REQUIRED, RECOMMENDED, or OPTIONAL . . . . . . . . 49
13. NFSv4.2 Operations . . . . . . . . . . . . . . . . . . . . . . 53 13. NFSv4.2 Operations . . . . . . . . . . . . . . . . . . . . . . 53
13.1. Operation 59: COPY - Initiate a server-side copy . . . . 53 13.1. Operation 59: COPY - Initiate a server-side copy . . . . 53
13.2. Operation 60: COPY_ABORT - Cancel a server-side copy . . 61 13.2. Operation 60: COPY_ABORT - Cancel a server-side copy . . 61
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 . . . . . . . . . . . . . . . . . . . . . . 62 a future copy . . . . . . . . . . . . . . . . . . . . . . 62
13.4. Operation 62: COPY_REVOKE - Revoke a destination 13.4. Operation 62: COPY_REVOKE - Revoke a destination
server's copy privileges . . . . . . . . . . . . . . . . 64 server's copy privileges . . . . . . . . . . . . . . . . 63
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 . . . . . . . . . . . . . . . . . . . . 65 server-side copy . . . . . . . . . . . . . . . . . . . . 64
13.6. Modification to Operation 42: EXCHANGE_ID - 13.6. Modification to Operation 42: EXCHANGE_ID -
Instantiate Client ID . . . . . . . . . . . . . . . . . . 66 Instantiate Client ID . . . . . . . . . . . . . . . . . . 66
13.7. Operation 64: INITIALIZE . . . . . . . . . . . . . . . . 67 13.7. Operation 64: INITIALIZE . . . . . . . . . . . . . . . . 67
13.8. Operation 67: IO_ADVISE - Application I/O access 13.8. Operation 67: IO_ADVISE - Application I/O access
pattern hints . . . . . . . . . . . . . . . . . . . . . . 71 pattern hints . . . . . . . . . . . . . . . . . . . . . . 70
13.9. Changes to Operation 51: LAYOUTRETURN . . . . . . . . . . 77 13.9. Changes to Operation 51: LAYOUTRETURN . . . . . . . . . . 76
13.10. Operation 65: READ_PLUS . . . . . . . . . . . . . . . . . 80 13.10. Operation 65: READ_PLUS . . . . . . . . . . . . . . . . . 79
13.11. Operation 66: SEEK . . . . . . . . . . . . . . . . . . . 85 13.11. Operation 66: SEEK . . . . . . . . . . . . . . . . . . . 84
14. NFSv4.2 Callback Operations . . . . . . . . . . . . . . . . . 86 14. NFSv4.2 Callback Operations . . . . . . . . . . . . . . . . . 85
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 . . . . . . . . . . . . . . 85
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 . . . . . . . . . . . . . . . . . . . . 86
15. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 89 15. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 88
16. References . . . . . . . . . . . . . . . . . . . . . . . . . . 89 16. References . . . . . . . . . . . . . . . . . . . . . . . . . . 88
16.1. Normative References . . . . . . . . . . . . . . . . . . 89 16.1. Normative References . . . . . . . . . . . . . . . . . . 88
16.2. Informative References . . . . . . . . . . . . . . . . . 90 16.2. Informative References . . . . . . . . . . . . . . . . . 89
Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 91
Appendix B. RFC Editor Notes . . . . . . . . . . . . . . . . . . 92 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 90
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 92 Appendix B. RFC Editor Notes . . . . . . . . . . . . . . . . . . 91
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 91
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 8, line 13 skipping to change at page 8, line 13
to perform a file copy on the server without the data being to perform a file copy on the server without the data being
transmitted back and forth over the network. transmitted back and forth over the network.
Without this feature, an NFS client copies data from one location to Without this feature, an NFS client copies data from one location to
another by reading the data from the server over the network, and another by reading the data from the server over the network, and
then writing the data back over the network to the server. Using then writing the data back over the network to the server. Using
this server-side copy operation, the client is able to instruct the this server-side copy operation, the client is able to instruct the
server to copy the data locally without the data being sent back and server to copy the data locally without the data being sent back and
forth over the network unnecessarily. forth over the network unnecessarily.
In general, this feature is useful whenever data is copied from one
location to another on the server. It is particularly useful when
copying the contents of a file from a backup. Backup-versions of a
file are copied for a number of reasons, including restoring and
cloning data.
If the source object and destination object are on different file If the source object and destination object are on different file
servers, the file servers will communicate with one another to servers, the file servers will communicate with one another to
perform the copy operation. The server-to-server protocol by which perform the copy operation. The server-to-server protocol by which
this is accomplished is not defined in this document. this is accomplished is not defined in this document.
2.2. Protocol Overview 2.2. Protocol Overview
The server-side copy offload operations support both intra-server and The server-side copy offload operations support both intra-server and
inter-server file copies. An intra-server copy is a copy in which inter-server file copies. An intra-server copy is a copy in which
the source file and destination file reside on the same server. In the source file and destination file reside on the same server. In
skipping to change at page 9, line 5 skipping to change at page 8, line 47
using other techniques. For example if the user wishes to copy a using other techniques. For example if the user wishes to copy a
directory, the client can synthesize a directory copy by first directory, the client can synthesize a directory copy by first
creating the destination directory and then copying the source creating the destination directory and then copying the source
directory's files to the new destination directory. If the user directory's files to the new destination directory. If the user
wishes to copy a namespace junction [11] [12], the client can use the wishes to copy a namespace junction [11] [12], the client can use the
ONC RPC Federated Filesystem protocol [12] to perform the copy. ONC RPC Federated Filesystem protocol [12] to perform the copy.
Specifically the client can determine the source junction's Specifically the client can determine the source junction's
attributes using the FEDFS_LOOKUP_FSN procedure and create a attributes using the FEDFS_LOOKUP_FSN procedure and create a
duplicate junction using the FEDFS_CREATE_JUNCTION procedure. duplicate junction using the FEDFS_CREATE_JUNCTION procedure.
For the inter-server copy protocol, the operations are defined to be For the inter-server copy, the operations are defined to be
compatible with a server-to-server copy protocol in which the compatible with the traditional copy authentication approach. The
destination server reads the file data from the source server. This client and user are authorized at the source for reading. Then they
model in which the file data is pulled from the source by the are authorized at the destination for writing.
destination has a number of advantages over a model in which the
source pushes the file data to the destination. The advantages of
the pull model include:
o The pull model only requires a remote server (i.e., the
destination server) to be granted read access. A push model
requires a remote server (i.e., the source server) to be granted
write access, which is more privileged.
o The pull model allows the destination server to stop reading if it
has run out of space. In a push model, the destination server
must flow control the source server in this situation.
o The pull model allows the destination server to easily flow
control the data stream by adjusting the size of its read
operations. In a push model, the destination server does not have
this ability. The source server in a push model is capable of
writing chunks larger than the destination server has requested in
attributes and session parameters. In theory, the destination
server could perform a "short" write in this situation, but this
approach is known to behave poorly in practice.
The following operations are provided to support server-side copy: 2.2.1. Overview of Copy Operations
COPY_NOTIFY: For inter-server copies, the client sends this COPY_NOTIFY: For inter-server copies, the client sends this
operation to the source server to notify it of a future file copy operation to the source server to notify it of a future file copy
from a given destination server for the given user. from a given destination server for the given user.
(Section 13.3)
COPY_REVOKE: Also for inter-server copies, the client sends this COPY_REVOKE: Also for inter-server copies, the client sends this
operation to the source server to revoke permission to copy a file operation to the source server to revoke permission to copy a file
for the given user. for the given user. (Section 13.4)
COPY: Used by the client to request a file copy. COPY: Used by the client to request a file copy. (Section 13.1)
COPY_ABORT: Used by the client to abort an asynchronous file copy. COPY_ABORT: Used by the client to abort an asynchronous file copy.
(Section 13.2)
COPY_STATUS: Used by the client to poll the status of an COPY_STATUS: Used by the client to poll the status of an
asynchronous file copy. asynchronous file copy. (Section 13.5)
CB_COPY: Used by the destination server to report the results of an CB_COPY: Used by the destination server to report the results of an
asynchronous file copy to the client. asynchronous file copy to the client. (Section 14.2)
These operations are described in detail in Section 2.3. This
section provides an overview of how these operations are used to
perform server-side copies.
2.2.1. Intra-Server Copy 2.2.2. Intra-Server Copy
To copy a file on a single server, the client uses a COPY operation. To copy a file on a single server, the client uses a COPY operation.
The server may respond to the copy operation with the final results The server may respond to the copy operation with the final results
of the copy or it may perform the copy asynchronously and deliver the of the copy or it may perform the copy asynchronously and deliver the
results using a CB_COPY operation callback. If the copy is performed results using a CB_COPY operation callback. If the copy is performed
asynchronously, the client may poll the status of the copy using asynchronously, the client may poll the status of the copy using
COPY_STATUS or cancel the copy using COPY_ABORT. COPY_STATUS or cancel the copy using COPY_ABORT.
A synchronous intra-server copy is shown in Figure 1. In this A synchronous intra-server copy is shown in Figure 1. In this
example, the NFS server chooses to perform the copy synchronously. example, the NFS server chooses to perform the copy synchronously.
skipping to change at page 11, line 25 skipping to change at page 10, line 33
| . | Multiple COPY_STATUS | . | Multiple COPY_STATUS
| . | operations may be sent. | . | operations may be sent.
| . | | . |
| | | |
|<-- CB_COPY --------------------------| Server reports results |<-- CB_COPY --------------------------| Server reports results
|\------------------------------------>| |\------------------------------------>|
| | | |
Figure 2: An asynchronous intra-server copy. Figure 2: An asynchronous intra-server copy.
2.2.2. Inter-Server Copy 2.2.3. Inter-Server Copy
A copy may also be performed between two servers. The copy protocol A copy may also be performed between two servers. The copy protocol
is designed to accommodate a variety of network topologies. As shown is designed to accommodate a variety of network topologies. As shown
in Figure 3, the client and servers may be connected by multiple in Figure 3, the client and servers may be connected by multiple
networks. In particular, the servers may be connected by a networks. In particular, the servers may be connected by a
specialized, high speed network (network 192.168.33.0/24 in the specialized, high speed network (network 192.168.33.0/24 in the
diagram) that does not include the client. The protocol allows the diagram) that does not include the client. The protocol allows the
client to setup the copy between the servers (over network client to setup the copy between the servers (over network
10.11.78.0/24 in the diagram) and for the servers to communicate on 10.11.78.0/24 in the diagram) and for the servers to communicate on
the high speed network if they choose to do so. the high speed network if they choose to do so.
skipping to change at page 14, line 39 skipping to change at page 13, line 39
| | . | | | . |
| | | | | |
| | | | | |
| | | | | |
|<-- CB_COPY --------------------------| Destination reports |<-- CB_COPY --------------------------| Destination reports
|\------------------------------------>| results |\------------------------------------>| results
| | | | | |
Figure 5: An asynchronous inter-server copy. Figure 5: An asynchronous inter-server copy.
2.2.3. Server-to-Server Copy Protocol 2.2.4. Server-to-Server Copy Protocol
During an inter-server copy, the destination server reads the file The source server and destination server are not required to use a
data from the source server. The source server and destination specific protocol to transfer the file data. The choice of what
server are not required to use a specific protocol to transfer the protocol to use is ultimately the destination server's decision.
file data. The choice of what protocol to use is ultimately the
destination server's decision.
2.2.3.1. Using NFSv4.x as a Server-to-Server Copy Protocol 2.2.4.1. Using NFSv4.x as a Server-to-Server Copy Protocol
The destination server MAY use standard NFSv4.x (where x >= 1) to The destination server MAY use standard NFSv4.x (where x >= 1) to
read the data from the source server. If NFSv4.x is used for the read the data from the source server. If NFSv4.x is used for the
server-to-server copy protocol, the destination server can use the server-to-server copy protocol, the destination server can use the
filehandle contained in the COPY request with standard NFSv4.x filehandle contained in the COPY request with standard NFSv4.x
operations to read data from the source server. Specifically, the operations to read data from the source server. Specifically, the
destination server may use the NFSv4.x OPEN operation's CLAIM_FH destination server may use the NFSv4.x OPEN operation's CLAIM_FH
facility to open the file being copied and obtain an open stateid. facility to open the file being copied and obtain an open stateid.
Using the stateid, the destination server may then use NFSv4.x READ Using the stateid, the destination server may then use NFSv4.x READ
operations to read the file. operations to read the file.
2.2.3.2. Using an alternative Server-to-Server Copy Protocol 2.2.4.2. Using an alternative Server-to-Server Copy Protocol
In a homogeneous environment, the source and destination servers In a homogeneous environment, the source and destination servers
might be able to perform the file copy extremely efficiently using might be able to perform the file copy extremely efficiently using
specialized protocols. For example the source and destination specialized protocols. For example the source and destination
servers might be two nodes sharing a common file system format for servers might be two nodes sharing a common file system format for
the source and destination file systems. Thus the source and the source and destination file systems. Thus the source and
destination are in an ideal position to efficiently render the image destination are in an ideal position to efficiently render the image
of the source file to the destination file by replicating the file of the source file to the destination file by replicating the file
system formats at the block level. Another possibility is that the system formats at the block level. Another possibility is that the
source and destination might be two nodes sharing a common storage source and destination might be two nodes sharing a common storage
area network, and thus there is no need to copy any data at all, and area network, and thus there is no need to copy any data at all, and
instead ownership of the file and its contents might simply be re- instead ownership of the file and its contents might simply be re-
assigned to the destination. To allow for these possibilities, the assigned to the destination. To allow for these possibilities, the
destination server is allowed to use a server-to-server copy protocol destination server is allowed to use a server-to-server copy protocol
of its choice. of its choice.
In a heterogeneous environment, using a protocol other than NFSv4.x In a heterogeneous environment, using a protocol other than NFSv4.x
(e.g,. HTTP [13] or FTP [14]) presents some challenges. In (e.g., HTTP [13] or FTP [14]) presents some challenges. In
particular, the destination server is presented with the challenge of particular, the destination server is presented with the challenge of
accessing the source file given only an NFSv4.x filehandle. accessing the source file given only an NFSv4.x filehandle.
One option for protocols that identify source files with path names One option for protocols that identify source files with path names
is to use an ASCII hexadecimal representation of the source is to use an ASCII hexadecimal representation of the source
filehandle as the file name. filehandle as the file name.
Another option for the source server is to use URLs to direct the Another option for the source server is to use URLs to direct the
destination server to a specialized service. For example, the destination server to a specialized service. For example, the
response to COPY_NOTIFY could include the URL response to COPY_NOTIFY could include the URL
skipping to change at page 16, line 5 skipping to change at page 15, line 5
port 9999 of s1.example.com. On port 9999 there would be a special port 9999 of s1.example.com. On port 9999 there would be a special
instance of the FTP service that understands how to convert NFS instance of the FTP service that understands how to convert NFS
filehandles to an open file descriptor (in many operating systems, filehandles to an open file descriptor (in many operating systems,
this would require a new system call, one which is the inverse of the this would require a new system call, one which is the inverse of the
makefh() function that the pre-NFSv4 MOUNT service needs). makefh() function that the pre-NFSv4 MOUNT service needs).
Authenticating and identifying the destination server to the source Authenticating and identifying the destination server to the source
server is also a challenge. Recommendations for how to accomplish server is also a challenge. Recommendations for how to accomplish
this are given in Section 2.4.1.2.4 and Section 2.4.1.4. this are given in Section 2.4.1.2.4 and Section 2.4.1.4.
2.3. Operations 2.3. Requirements for Operations
In the sections that follow, several operations are defined that The implementation of server-side copy is OPTIONAL by the client and
together provide the server-side copy feature. These operations are the server. However, in order to successfully copy a file, some
intended to be OPTIONAL operations as defined in section 17 of [2]. operations MUST be supported by the client and/or server.
The COPY_NOTIFY, COPY_REVOKE, COPY, COPY_ABORT, and COPY_STATUS
operations are designed to be sent within an NFSv4 COMPOUND If a client desires an intra-server file copy, then it MUST support
procedure. The CB_COPY operation is designed to be sent within an the COPY and CB_COPY operations. If COPY returns a stateid, then the
NFSv4 CB_COMPOUND procedure. client MAY use the COPY_ABORT and COPY_STATUS operations.
If a client desires an inter-server file copy, then it MUST support
the COPY, COPY_NOTICE, and CB_COPY operations, and MAY use the
COPY_REVOKE operation. If COPY returns a stateid, then the client
MAY use the COPY_ABORT and COPY_STATUS operations.
If a server supports intra-server copy, then the server MUST support
the COPY operation. If a server's COPY operation returns a stateid,
then the server MUST also support these operations: CB_COPY,
COPY_ABORT, and COPY_STATUS.
If a source server supports inter-server copy, then the source server
MUST support all these operations: COPY_NOTIFY and COPY_REVOKE. If a
destination server supports inter-server copy, then the destination
server MUST support the COPY operation. If a destination server's
COPY operation returns a stateid, then the destination server MUST
also support these operations: CB_COPY, COPY_ABORT, COPY_NOTIFY,
COPY_REVOKE, and COPY_STATUS.
Each operation is performed in the context of the user identified by Each operation is performed in the context of the user identified by
the ONC RPC credential of its containing COMPOUND or CB_COMPOUND the ONC RPC credential of its containing COMPOUND or CB_COMPOUND
request. For example, a COPY_ABORT operation issued by a given user request. For example, a COPY_ABORT operation issued by a given user
indicates that a specified COPY operation initiated by the same user indicates that a specified COPY operation initiated by the same user
be canceled. Therefore a COPY_ABORT MUST NOT interfere with a copy be canceled. Therefore a COPY_ABORT MUST NOT interfere with a copy
of the same file initiated by another user. of the same file initiated by another user.
An NFS server MAY allow an administrative user to monitor or cancel An NFS server MAY allow an administrative user to monitor or cancel
copy operations using an implementation specific interface. copy operations using an implementation specific interface.
skipping to change at page 17, line 22 skipping to change at page 16, line 46
and CB_COPY operations. and CB_COPY operations.
Section 8.2.4 of [2] specifies that stateids are valid until either Section 8.2.4 of [2] 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 copy offload stateid will be valid until either (A) the client or
server restarts or (B) the client returns the resource by issuing a server restarts or (B) the client returns the resource by issuing a
COPY_ABORT operation or the client replies to a CB_COPY operation. COPY_ABORT operation or the client replies to a CB_COPY operation.
A copy offload stateid's seqid MUST NOT be 0 (zero). In the context A copy offload stateid's seqid MUST NOT be 0. In the context of a
of a copy offload operation, it is ambiguous to indicate the most copy offload operation, it is ambiguous to indicate the most recent
recent copy offload operation using a stateid with seqid of 0 (zero). copy offload operation using a stateid with seqid of 0. Therefore a
Therefore a copy offload stateid with seqid of 0 (zero) MUST be copy offload stateid with seqid of 0 MUST be considered invalid.
considered invalid.
2.4. Security Considerations 2.4. Security Considerations
The security considerations pertaining to NFSv4 [10] apply to this The security considerations pertaining to NFSv4 [10] apply to this
document. chapter.
The standard security mechanisms provide by NFSv4 [10] may be used to The standard security mechanisms provide by NFSv4 [10] may be used to
secure the protocol described in this document. secure the protocol described in this chapter.
NFSv4 clients and servers supporting the the inter-server copy NFSv4 clients and servers supporting the inter-server copy operations
operations described in this document are REQUIRED to implement [5], described in this chapter are REQUIRED to implement [5], including
including the RPCSEC_GSSv3 privileges copy_from_auth and the RPCSEC_GSSv3 privileges copy_from_auth and copy_to_auth. If the
copy_to_auth. If the server-to-server copy protocol is ONC RPC server-to-server copy protocol is ONC RPC based, the servers are also
based, the servers are also REQUIRED to implement the RPCSEC_GSSv3 REQUIRED to implement the RPCSEC_GSSv3 privilege copy_confirm_auth.
privilege copy_confirm_auth. These requirements to implement are not These requirements to implement are not requirements to use. NFSv4
requirements to use. NFSv4 clients and servers are RECOMMENDED to clients and servers are RECOMMENDED to use [5] to secure server-side
use [5] to secure server-side copy operations. copy operations.
2.4.1. Inter-Server Copy Security 2.4.1. Inter-Server Copy Security
2.4.1.1. Requirements for Secure Inter-Server Copy 2.4.1.1. Requirements for Secure Inter-Server Copy
Inter-server copy is driven by several requirements: Inter-server copy is driven by several requirements:
o The specification MUST NOT mandate an inter-server copy protocol. o The specification MUST NOT mandate an inter-server copy protocol.
There are many ways to copy data. Some will be more optimal than There are many ways to copy data. Some will be more optimal than
others depending on the identities of the source server and others depending on the identities of the source server and
skipping to change at page 24, line 33 skipping to change at page 24, line 8
For protocols that authenticate user names with passwords (e.g., HTTP For protocols that authenticate user names with passwords (e.g., HTTP
[13] and FTP [14]), the nfsv4 user id could be used as the user name, [13] and FTP [14]), the nfsv4 user id could be used as the user name,
and an ASCII hexadecimal representation of the RPCSEC_GSSv3 shared and an ASCII hexadecimal representation of the RPCSEC_GSSv3 shared
secret could be used as the user password or as input into non- secret could be used as the user password or as input into non-
password authentication methods like CHAP [15]. password authentication methods like CHAP [15].
2.4.1.3. Inter-Server Copy via ONC RPC but without RPCSEC_GSSv3 2.4.1.3. Inter-Server Copy via ONC RPC but without RPCSEC_GSSv3
ONC RPC security flavors other than RPCSEC_GSSv3 MAY be used with the ONC RPC security flavors other than RPCSEC_GSSv3 MAY be used with the
server-side copy offload operations described in this document. In server-side copy offload operations described in this chapter. In
particular, host-based ONC RPC security flavors such as AUTH_NONE and particular, host-based ONC RPC security flavors such as AUTH_NONE and
AUTH_SYS MAY be used. If a host-based security flavor is used, a AUTH_SYS MAY be used. If a host-based security flavor is used, a
minimal level of protection for the server-to-server copy protocol is minimal level of protection for the server-to-server copy protocol is
possible. possible.
In the absence of strong security mechanisms such as RPCSEC_GSSv3, In the absence of strong security mechanisms such as RPCSEC_GSSv3,
the challenge is how the source server and destination server the challenge is how the source server and destination server
identify themselves to each other, especially in the presence of identify themselves to each other, especially in the presence of
multi-homed source and destination servers. In a multi-homed multi-homed source and destination servers. In a multi-homed
environment, the destination server might not contact the source environment, the destination server might not contact the source
skipping to change at page 31, line 25 skipping to change at page 30, line 45
The following operations and attributes can be used to resolve this The following operations and attributes can be used to resolve this
issues: issues:
space_reserved This attribute specifies whether the blocks backing space_reserved This attribute specifies whether the blocks backing
the file have been preallocated. the file have been preallocated.
space_freed This attribute specifies the space freed when a file is space_freed This attribute specifies the space freed when a file is
deleted, taking block sharing into consideration. deleted, taking block sharing into consideration.
INITIALIZED This operation zeroes and/or deallocates the blocks INITIALIZE This operation zeroes and/or deallocates the blocks
backing a region of the file. backing a region of the file.
If space_used of a file is interpreted to mean the size in bytes of If space_used of a file is interpreted to mean the size in bytes of
all disk blocks pointed to by the inode of the file, then shared all disk blocks pointed to by the inode of the file, then shared
blocks get double counted, over-reporting the space utilization. blocks get double counted, over-reporting the space utilization.
This also has the adverse effect that the deletion of a file with This also has the adverse effect that the deletion of a file with
shared blocks frees up less than space_used bytes. shared blocks frees up less than space_used bytes.
On the other hand, if space_used is interpreted to mean the size in On the other hand, if space_used is interpreted to mean the size in
bytes of those disk blocks unique to the inode of the file, then bytes of those disk blocks unique to the inode of the file, then
skipping to change at page 46, line 4 skipping to change at page 45, line 21
10.1.2.1. NFS4ERR_METADATA_NOTSUPP (Error Code 10090) 10.1.2.1. NFS4ERR_METADATA_NOTSUPP (Error Code 10090)
The destination file cannot support the same metadata as the source The destination file cannot support the same metadata as the source
file. file.
10.1.2.2. NFS4ERR_OFFLOAD_DENIED (Error Code 10091) 10.1.2.2. NFS4ERR_OFFLOAD_DENIED (Error Code 10091)
The copy offload operation is supported by both the source and the The copy offload operation is supported by both the source and the
destination, but the destination is not allowing it for this file. destination, but the destination is not allowing it for this file.
If the client sees this error, it should fall back to the normal copy If the client sees this error, it should fall back to the normal copy
semantics. semantics.
10.1.2.3. NFS4ERR_PARTNER_NO_AUTH (Error Code 10089) 10.1.2.3. NFS4ERR_PARTNER_NO_AUTH (Error Code 10089)
The remote server does not authorize a server-to-server copy offload The source server does not authorize a server-to-server copy offload
operation. This may be due to the client's failure to send the operation. This may be due to the client's failure to send the
COPY_NOTIFY operation to the remote server, the remote server COPY_NOTIFY operation to the source server, the source server
receiving a server-to-server copy offload request after the copy receiving a server-to-server copy offload request after the copy
lease time expired, or for some other permission problem. lease time expired, or for some other permission problem.
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
skipping to change at page 55, line 12 skipping to change at page 54, line 40
PUTFH source-fh PUTFH source-fh
SAVEFH SAVEFH
If the request is for a server-to-server copy, the source-fh is a If the request is for a server-to-server copy, the source-fh is a
filehandle from the source server and the compound procedure is being filehandle from the source server and the compound procedure is being
executed on the destination server. In this case, the source-fh is a executed on the destination server. In this case, the source-fh is a
foreign filehandle on the server receiving the COPY request. If foreign filehandle on the server receiving the COPY request. If
either PUTFH or SAVEFH checked the validity of the filehandle, the either PUTFH or SAVEFH checked the validity of the filehandle, the
operation would likely fail and return NFS4ERR_STALE. operation would likely fail and return NFS4ERR_STALE.
In order to avoid this problem, the minor version incorporating the If a server supports the server-to-server COPY feature, a PUTFH
COPY operations will need to make a few small changes in the handling followed by a SAVEFH MUST NOT return NFS4ERR_STALE for either
of existing operations. If a server supports the server-to-server operation. These restrictions do not pose substantial difficulties
COPY feature, a PUTFH followed by a SAVEFH MUST NOT return for servers. The CURRENT_FH and SAVED_FH may be validated in the
NFS4ERR_STALE for either operation. These restrictions do not pose context of the operation referencing them and an NFS4ERR_STALE error
substantial difficulties for servers. The CURRENT_FH and SAVED_FH returned for an invalid file handle at that point.
may be validated in the context of the operation referencing them and
an NFS4ERR_STALE error returned for an invalid file handle at that
point.
The CURRENT_FH and ca_destination together specify the destination of The CURRENT_FH and ca_destination together specify the destination of
the copy operation. If ca_destination is of 0 (zero) length, then the copy operation. If ca_destination is of 0 (zero) length, then
CURRENT_FH specifies the target file. In this case, CURRENT_FH MUST CURRENT_FH specifies the target file. In this case, CURRENT_FH MUST
be a regular file and not a directory. If ca_destination is not of 0 be a regular file and not a directory. If ca_destination is not of 0
(zero) length, the ca_destination argument specifies the file name to (zero) length, the ca_destination argument specifies the file name to
which the data will be copied within the directory identified by which the data will be copied within the directory identified by
CURRENT_FH. In this case, CURRENT_FH MUST be a directory and not a CURRENT_FH. In this case, CURRENT_FH MUST be a directory and not a
regular file. regular file.
skipping to change at page 56, line 26 skipping to change at page 56, line 4
If the destination file is created as a result of this command, the If the destination file is created as a result of this command, the
destination file's size will be equal to the number of bytes destination file's size will be equal to the number of bytes
successfully copied. If the destination file already existed, the successfully copied. If the destination file already existed, the
destination file's size may increase as a result of this operation destination file's size may increase as a result of this operation
(e.g. if ca_dst_offset plus ca_count is greater than the (e.g. if ca_dst_offset plus ca_count is greater than the
destination's initial size). destination's initial size).
If the ca_source_server list is specified, then this is an inter- If the ca_source_server list is specified, then this is an inter-
server copy operation and the source file is on a remote server. The server copy operation and the source file is on a remote server. The
client is expected to have previously issued a successful COPY_NOTIFY client is expected to have previously issued a successful COPY_NOTIFY
request to the remote source server. The ca_source_server list request to the remote source server. The ca_source_server list MUST
SHOULD be the same as the COPY_NOTIFY response's cnr_source_server be the same as the COPY_NOTIFY response's cnr_source_server list. If
list. If the client includes the entries from the COPY_NOTIFY the client includes the entries from the COPY_NOTIFY response's
response's cnr_source_server list in the ca_source_server list, the cnr_source_server list in the ca_source_server list, the source
source server can indicate a specific copy protocol for the server can indicate a specific copy protocol for the destination
destination server to use by returning a URL, which specifies both a server to use by returning a URL, which specifies both a protocol
protocol service and server name. Server-to-server copy protocol service and server name. Server-to-server copy protocol
considerations are described in Section 2.2.3 and Section 2.4.1. considerations are described in Section 2.2.4 and Section 2.4.1.
The ca_flags argument allows the copy operation to be customized in The ca_flags argument allows the copy operation to be customized in
the following ways using the guarded flag (COPY4_GUARDED) and the the following ways using the guarded flag (COPY4_GUARDED) and the
metadata flag (COPY4_METADATA). metadata flag (COPY4_METADATA).
If the guarded flag is set and the destination exists on the server, If the guarded flag is set and the destination exists on the server,
this operation will fail with NFS4ERR_EXIST. this operation will fail with NFS4ERR_EXIST.
If the guarded flag is not set and the destination exists on the If the guarded flag is not set and the destination exists on the
server, the behavior is implementation dependent. server, the behavior is implementation dependent.
If the metadata flag is set and the client is requesting a whole file If the metadata flag is set and the client is requesting a whole file
copy (i.e., ca_count is 0 (zero)), a subset of the destination file's copy (i.e., ca_count is 0 (zero)), a subset of the destination file's
attributes MUST be the same as the source file's corresponding attributes MUST be the same as the source file's corresponding
attributes and a subset of the destination file's attributes SHOULD attributes and a subset of the destination file's attributes SHOULD
be the same as the source file's corresponding attributes. The be the same as the source file's corresponding attributes. The
attributes in the MUST and SHOULD copy subsets will be defined for attributes in the MUST and SHOULD copy subsets will be defined for
each NFS version. each NFS version.
For NFSv4.2, Table 3 and Table 4 list the REQUIRED and RECOMMENDED For NFSv4.2, Table 3 and Table 4 list the REQUIRED and RECOMMENDED
attributes respectively. A "MUST" in the "Copy to destination file?" attributes respectively. In the "Copy to destination file?" column,
column indicates that the attribute is part of the MUST copy set. A a "MUST" indicates that the attribute is part of the MUST copy set.
"SHOULD" in the "Copy to destination file?" column indicates that the A "SHOULD" indicates that the attribute is part of the SHOULD copy
attribute is part of the SHOULD copy set. set. A "no" indicates that the attribute MUST NOT be copied.
REQUIRED attributes
+--------------------+----+---------------------------+ +--------------------+----+---------------------------+
| Name | Id | Copy to destination file? | | Name | Id | Copy to destination file? |
+--------------------+----+---------------------------+ +--------------------+----+---------------------------+
| supported_attrs | 0 | no | | supported_attrs | 0 | no |
| type | 1 | MUST | | type | 1 | MUST |
| fh_expire_type | 2 | no | | fh_expire_type | 2 | no |
| change | 3 | SHOULD | | change | 3 | SHOULD |
| size | 4 | MUST | | size | 4 | MUST |
| link_support | 5 | no | | link_support | 5 | no |
skipping to change at page 57, line 32 skipping to change at page 57, line 28
| fsid | 8 | no | | fsid | 8 | no |
| unique_handles | 9 | no | | unique_handles | 9 | no |
| lease_time | 10 | no | | lease_time | 10 | no |
| rdattr_error | 11 | no | | rdattr_error | 11 | no |
| filehandle | 19 | no | | filehandle | 19 | no |
| suppattr_exclcreat | 75 | no | | suppattr_exclcreat | 75 | no |
+--------------------+----+---------------------------+ +--------------------+----+---------------------------+
Table 3 Table 3
RECOMMENDED attributes
+--------------------+----+---------------------------+ +--------------------+----+---------------------------+
| Name | Id | Copy to destination file? | | Name | Id | Copy to destination file? |
+--------------------+----+---------------------------+ +--------------------+----+---------------------------+
| acl | 12 | MUST | | acl | 12 | MUST |
| aclsupport | 13 | no | | aclsupport | 13 | no |
| archive | 14 | no | | archive | 14 | no |
| cansettime | 15 | no | | cansettime | 15 | no |
| case_insensitive | 16 | no | | case_insensitive | 16 | no |
| case_preserving | 17 | no | | case_preserving | 17 | no |
| change_attr_type | 79 | no | | change_attr_type | 79 | no |
skipping to change at page 61, line 4 skipping to change at page 60, line 47
o NFS4ERR_NOTDIR o NFS4ERR_NOTDIR
o NFS4ERR_WRONG_TYPE o NFS4ERR_WRONG_TYPE
o NFS4ERR_ISDIR o NFS4ERR_ISDIR
o NFS4ERR_INVAL o NFS4ERR_INVAL
o NFS4ERR_DELAY o NFS4ERR_DELAY
o NFS4ERR_METADATA_NOTSUPP o NFS4ERR_METADATA_NOTSUPP
o NFS4ERR_WRONGSEC o NFS4ERR_WRONGSEC
13.2. Operation 60: COPY_ABORT - Cancel a server-side copy 13.2. Operation 60: COPY_ABORT - Cancel a server-side copy
13.2.1. ARGUMENT 13.2.1. ARGUMENT
struct COPY_ABORT4args { struct COPY_ABORT4args {
/* CURRENT_FH: desination file */ /* CURRENT_FH: destination file */
stateid4 caa_stateid; stateid4 caa_stateid;
}; };
13.2.2. RESULT 13.2.2. RESULT
struct COPY_ABORT4res { struct COPY_ABORT4res {
nfsstat4 car_status; nfsstat4 car_status;
}; };
13.2.3. DESCRIPTION 13.2.3. DESCRIPTION
skipping to change at page 61, line 40 skipping to change at page 61, line 37
requested the copy exits before the operation is completed or for requested the copy exits before the operation is completed or for
some other reason. some other reason.
The request contains the filehandle and copy stateid cookies that act The request contains the filehandle and copy stateid cookies that act
as the context for the previously initiated copy operation. as the context for the previously initiated copy operation.
The result's car_status field indicates whether the cancel was The result's car_status field indicates whether the cancel was
successful or not. A value of NFS4_OK indicates that the copy successful or not. A value of NFS4_OK indicates that the copy
operation was canceled and no callback will be issued by the server. operation was canceled and no callback will be issued by the server.
A copy operation that is successfully canceled may result in none, A copy operation that is successfully canceled may result in none,
some, or all of the data copied. some, or all of the data and/or metadata copied.
If the server supports asynchronous copies, the server is REQUIRED to If the server supports asynchronous copies, the server is REQUIRED to
support the COPY_ABORT operation. support the COPY_ABORT operation.
The COPY_ABORT operation may fail for the following reasons (this is The COPY_ABORT operation may fail for the following reasons (this is
a partial list): a partial list):
o NFS4ERR_NOTSUPP o NFS4ERR_NOTSUPP
o NFS4ERR_RETRY o NFS4ERR_RETRY
o NFS4ERR_COMPLETE_ALREADY o NFS4ERR_COMPLETE_ALREADY
o NFS4ERR_SERVERFAULT o NFS4ERR_SERVERFAULT
13.3. Operation 61: COPY_NOTIFY - Notify a source server of a future 13.3. Operation 61: COPY_NOTIFY - Notify a source server of a future
copy copy
13.3.1. ARGUMENT 13.3.1. ARGUMENT
struct COPY_NOTIFY4args { struct COPY_NOTIFY4args {
/* CURRENT_FH: source file */ /* CURRENT_FH: source file */
netloc4 cna_destination_server; netloc4 cna_destination_server;
skipping to change at page 62, line 47 skipping to change at page 62, line 43
operation in a COMPOUND request to the source server to authorize a operation in a COMPOUND request to the source server to authorize a
destination server identified by cna_destination_server to read the destination server identified by cna_destination_server to read the
file specified by CURRENT_FH on behalf of the given user. file specified by CURRENT_FH on behalf of the given user.
The cna_destination_server MUST be specified using the netloc4 The cna_destination_server MUST be specified using the netloc4
network location format. The server is not required to resolve the network location format. The server is not required to resolve the
cna_destination_server address before completing this operation. cna_destination_server address before completing this operation.
If this operation succeeds, the source server will allow the If this operation succeeds, the source server will allow the
cna_destination_server to copy the specified file on behalf of the cna_destination_server to copy the specified file on behalf of the
given user. If COPY_NOTIFY succeeds, the destination server is given user as long as both of the following conditions are met:
granted permission to read the file as long as both of the following
conditions are met:
o The destination server begins reading the source file before the o The destination server begins reading the source file before the
cnr_lease_time expires. If the cnr_lease_time expires while the cnr_lease_time expires. If the cnr_lease_time expires while the
destination server is still reading the source file, the destination server is still reading the source file, the
destination server is allowed to finish reading the file. destination server is allowed to finish reading the file.
o The client has not issued a COPY_REVOKE for the same combination o The client has not issued a COPY_REVOKE for the same combination
of user, filehandle, and destination server. of user, filehandle, and destination server.
The cnr_lease_time is chosen by the source server. A cnr_lease_time The cnr_lease_time is chosen by the source server. A cnr_lease_time
of 0 (zero) indicates an infinite lease. To renew the copy lease of 0 (zero) indicates an infinite lease. To avoid the need for
time the client should resend the same copy notification request to synchronized clocks, copy lease times are granted by the server as a
the source server. time delta. To renew the copy lease time the client should resend
the same copy notification request to the source server.
To avoid the need for synchronized clocks, copy lease times are
granted by the server as a time delta. However, there is a
requirement that the client and server clocks do not drift
excessively over the duration of the lease. There is also the issue
of propagation delay across the network which could easily be several
hundred milliseconds as well as the possibility that requests will be
lost and need to be retransmitted.
To take propagation delay into account, the client should subtract it
from copy lease times (e.g., if the client estimates the one-way
propagation delay as 200 milliseconds, then it can assume that the
lease is already 200 milliseconds old when it gets it). In addition,
it will take another 200 milliseconds to get a response back to the
server. So the client must send a lease renewal or send the copy
offload request to the cna_destination_server at least 400
milliseconds before the copy lease would expire. If the propagation
delay varies over the life of the lease (e.g., the client is on a
mobile host), the client will need to continuously subtract the
increase in propagation delay from the copy lease times.
The server's copy lease period configuration should take into account
the network distance of the clients that will be accessing the
server's resources. It is expected that the lease period will take
into account the network propagation delays and other network delay
factors for the client population. Since the protocol does not allow
for an automatic method to determine an appropriate copy lease
period, the server's administrator may have to tune the copy lease
period.
A successful response will also contain a list of names, addresses, A successful response will also contain a list of netloc4 network
and URLs called cnr_source_server, on which the source is willing to location formats called cnr_source_server, on which the source is
accept connections from the destination. These might not be willing to accept connections from the destination. These might not
reachable from the client and might be located on networks to which be reachable from the client and might be located on networks to
the client has no connection. which the client has no connection.
If the client wishes to perform an inter-server copy, the client MUST If the client wishes to perform an inter-server copy, the client MUST
send a COPY_NOTIFY to the source server. Therefore, the source send a COPY_NOTIFY to the source server. Therefore, the source
server MUST support COPY_NOTIFY. server MUST support COPY_NOTIFY.
For a copy only involving one server (the source and destination are For a copy only involving one server (the source and destination are
on the same server), this operation is unnecessary. on the same server), this operation is unnecessary.
The COPY_NOTIFY operation may fail for the following reasons (this is The COPY_NOTIFY operation may fail for the following reasons (this is
a partial list): a partial list):
skipping to change at page 65, line 6 skipping to change at page 64, line 19
authorization of a destination server identified by authorization of a destination server identified by
cra_destination_server from reading the file specified by CURRENT_FH cra_destination_server from reading the file specified by CURRENT_FH
on behalf of given user. If the cra_destination_server has already on behalf of given user. If the cra_destination_server has already
begun copying the file, a successful return from this operation begun copying the file, a successful return from this operation
indicates that further access will be prevented. indicates that further access will be prevented.
The cra_destination_server MUST be specified using the netloc4 The cra_destination_server MUST be specified using the netloc4
network location format. The server is not required to resolve the network location format. The server is not required to resolve the
cra_destination_server address before completing this operation. cra_destination_server address before completing this operation.
The COPY_REVOKE operation is useful in situations in which the source The client uses COPY_ABORT to inform the destination to stop the
server granted a very long or infinite lease on the destination active transfer and COPY_REVOKE to inform the source to not allow any
server's ability to read the source file and all copy operations on more copy requests from the destination. The COPY_REVOKE operation
the source file have been completed. is also useful in situations in which the source server granted a
very long or infinite lease on the destination server's ability to
read the source file and all copy operations on the source file have
been completed.
For a copy only involving one server (the source and destination are For a copy only involving one server (the source and destination are
on the same server), this operation is unnecessary. on the same server), this operation is unnecessary.
If the server supports COPY_NOTIFY, the server is REQUIRED to support If the server supports COPY_NOTIFY, the server is REQUIRED to support
the COPY_REVOKE operation. the COPY_REVOKE operation.
The COPY_REVOKE operation may fail for the following reasons (this is The COPY_REVOKE operation may fail for the following reasons (this is
a partial list): a partial list):
skipping to change at page 66, line 9 skipping to change at page 65, line 23
case NFS4_OK: case NFS4_OK:
COPY_STATUS4resok resok4; COPY_STATUS4resok resok4;
default: default:
void; void;
}; };
13.5.3. DESCRIPTION 13.5.3. DESCRIPTION
COPY_STATUS is used for both intra- and inter-server asynchronous COPY_STATUS is used for both intra- and inter-server asynchronous
copies. The COPY_STATUS operation allows the client to poll the copies. The COPY_STATUS operation allows the client to poll the
server to determine the status of an asynchronous copy operation. destination server to determine the status of an asynchronous copy
This operation is sent by the client to the destination server. operation.
If this operation is successful, the number of bytes copied are If this operation is successful, the number of bytes copied are
returned to the client in the csr_bytes_copied field. The returned to the client in the csr_bytes_copied field. The
csr_bytes_copied value indicates the number of bytes copied but not csr_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 optional csr_complete field is present, the copy has If the optional csr_complete field is present, the copy has
completed. In this case the status value indicates the result of the completed. In this case the status value indicates the result of the
asynchronous copy operation. In all cases, the server will also asynchronous copy operation. In all cases, the server will also
deliver the final results of the asynchronous copy in a CB_COPY deliver the final results of the asynchronous copy in a CB_COPY
skipping to change at page 67, line 22 skipping to change at page 66, line 33
the session is lost, there is no way to know when any in progress the session is lost, there is no way to know when any in progress
operations have aborted or completed. In hindsight, the NFSv4.1 operations have aborted or completed. In hindsight, the NFSv4.1
specification should have mandated that DESTROY_SESSION either abort specification should have mandated that DESTROY_SESSION either abort
or complete all outstanding operations. or complete all outstanding operations.
13.6.4. DESCRIPTION 13.6.4. DESCRIPTION
A client SHOULD request the EXCHGID4_FLAG_SUPP_FENCE_OPS capability A client SHOULD request the EXCHGID4_FLAG_SUPP_FENCE_OPS capability
when it sends an EXCHANGE_ID operation. The server SHOULD set this when it sends an EXCHANGE_ID operation. The server SHOULD set this
capability in the EXCHANGE_ID reply whether the client requests it or capability in the EXCHANGE_ID reply whether the client requests it or
not. If the client ID is created with this capability then the not. It is the server's return that determines whether this
following will occur: capability is in effect. When it is in effect, the following will
occur:
o The server will not reply to any DESTROY_SESSION invoked with the o The server will not reply to any DESTROY_SESSION invoked with the
client ID until all operations in progress are completed or client ID until all operations in progress are completed or
aborted. aborted.
o The server will not reply to subsequent EXCHANGE_ID invoked on the o The server will not reply to subsequent EXCHANGE_ID invoked on the
same client owner with a new verifier until all operations in same client owner with a new verifier until all operations in
progress on the client ID's session are completed or aborted. progress on the client ID's session are completed or aborted.
o When DESTROY_CLIENTID is invoked, if there are sessions (both idle
and non-idle), opens, locks, delegations, layouts, and/or wants
(Section 18.49 of [2]) associated with the client ID are removed.
Pending operations will be completed or aborted before the
sessions, opens, locks, delegations, layouts, and/or wants are
deleted.
o The NFS server SHOULD support client ID trunking, and if it does o The NFS server SHOULD support client ID trunking, and if it does
and the EXCHGID4_FLAG_SUPP_FENCE_OPS capability is enabled, then a and the EXCHGID4_FLAG_SUPP_FENCE_OPS capability is enabled, then a
session ID created on one node of the storage cluster MUST be session ID created on one node of the storage cluster MUST be
destroyable via DESTROY_SESSION. In addition, DESTROY_CLIENTID destroyable via DESTROY_SESSION. In addition, DESTROY_CLIENTID
and an EXCHANGE_ID with a new verifier affects all sessions and an EXCHANGE_ID with a new verifier affects all sessions
regardless what node the sessions were created on. regardless what node the sessions were created on.
13.7. Operation 64: INITIALIZE 13.7. Operation 64: INITIALIZE
This operation can be used to initialize the structure imposed by an This operation can be used to initialize the structure imposed by an
skipping to change at page 88, line 37 skipping to change at page 87, line 37
CB_COPY is used for both intra- and inter-server asynchronous copies. CB_COPY is used for both intra- and inter-server asynchronous copies.
The CB_COPY callback informs the client of the result of an The CB_COPY callback informs the client of the result of an
asynchronous server-side copy. This operation is sent by the asynchronous server-side copy. This operation is sent by the
destination server to the client in a CB_COMPOUND request. The copy destination server to the client in a CB_COMPOUND request. The copy
is identified by the filehandle and stateid arguments. The result is is identified by the filehandle and stateid arguments. The result is
indicated by the status field. If the copy failed, cca_bytes_copied indicated by the status field. If the copy failed, cca_bytes_copied
contains the number of bytes copied before the failure occurred. The contains the number of bytes copied before the failure occurred. The
cca_bytes_copied value indicates the number of bytes copied but not cca_bytes_copied value indicates the number of bytes copied but not
which specific bytes have been copied. which specific bytes have been copied.
In the absence of an established backchannel, the server cannot
signal the completion of the COPY via a CB_COPY callback. The loss
of a callback channel would be indicated by the server setting the
SEQ4_STATUS_CB_PATH_DOWN flag in the sr_status_flags field of the
SEQUENCE operation. The client must re-establish the callback
channel to receive the status of the COPY operation. Prolonged loss
of the callback channel could result in the server dropping the COPY
operation state and invalidating the copy stateid.
If the client supports the COPY operation, the client is REQUIRED to If the client supports the COPY operation, the client is REQUIRED to
support the CB_COPY operation. support the CB_COPY operation.
There is a potential race between the reply to the original COPY on
the forechannel and the CB_COPY callback on the backchannel.
Sections 2.10.6.3 and 20.9.3 in [2] describes how to handle this type
of issue.
The CB_COPY operation may fail for the following reasons (this is a The CB_COPY operation may fail for the following reasons (this is a
partial list): partial list):
NFS4ERR_NOTSUPP: The copy offload operation is not supported by the NFS4ERR_NOTSUPP: The copy offload operation is not supported by the
NFS client receiving this request. NFS client receiving this request.
15. IANA Considerations 15. IANA Considerations
This section uses terms that are defined in [25]. This section uses terms that are defined in [25].
skipping to change at page 92, line 5 skipping to change at page 91, line 5
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,
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
smoothly. While many people contributed here and there, the core
reviewers were Andy Adamson, Pranoop Erasani, Bruce Fields, Chuck
Lever, Trond Myklebust, David Noveck, and Peter Staubach.
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]
Author's Address Author's Address
 End of changes. 68 change blocks. 
219 lines changed or deleted 176 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/