draft-ietf-nfsv4-rfc3530bis-10.txt | draft-ietf-nfsv4-rfc3530bis-11.txt | |||
---|---|---|---|---|
NFSv4 T. Haynes, Ed. | NFSv4 T. Haynes, Ed. | |||
Internet-Draft NetApp | Internet-Draft NetApp | |||
Intended status: Standards Track D. Noveck, Ed. | Intended status: Standards Track D. Noveck, Ed. | |||
Expires: September 14, 2011 EMC | Expires: October 6, 2011 EMC | |||
March 13, 2011 | April 04, 2011 | |||
Network File System (NFS) Version 4 Protocol | Network File System (NFS) Version 4 Protocol | |||
draft-ietf-nfsv4-rfc3530bis-10.txt | draft-ietf-nfsv4-rfc3530bis-11.txt | |||
Abstract | Abstract | |||
The Network File System (NFS) version 4 is a distributed filesystem | The Network File System (NFS) version 4 is a distributed filesystem | |||
protocol which owes heritage to NFS protocol version 2, RFC 1094, and | protocol which owes heritage to NFS protocol version 2, RFC 1094, and | |||
version 3, RFC 1813. Unlike earlier versions, the NFS version 4 | version 3, RFC 1813. Unlike earlier versions, the NFS version 4 | |||
protocol supports traditional file access while integrating support | protocol supports traditional file access while integrating support | |||
for file locking and the mount protocol. In addition, support for | for file locking and the mount protocol. In addition, support for | |||
strong security (and its negotiation), compound operations, client | strong security (and its negotiation), compound operations, client | |||
caching, and internationalization have been added. Of course, | caching, and internationalization have been added. Of course, | |||
skipping to change at page 1, line 35 | skipping to change at page 1, line 35 | |||
replaces RFC 3530 as the definition of the NFS version 4 protocol. | replaces RFC 3530 as the definition of the NFS version 4 protocol. | |||
Requirements Language | Requirements Language | |||
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", | |||
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this | "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this | |||
document are to be interpreted as described in RFC 2119 [1]. | document are to be interpreted as described in RFC 2119 [1]. | |||
Status of this Memo | Status of this Memo | |||
This Internet-Draft is submitted to IETF in full conformance with the | This Internet-Draft is submitted in full conformance with the | |||
provisions of BCP 78 and BCP 79. | provisions of BCP 78 and BCP 79. | |||
Internet-Drafts are working documents of the Internet Engineering | Internet-Drafts are working documents of the Internet Engineering | |||
Task Force (IETF), its areas, and its working groups. Note that | Task Force (IETF). Note that other groups may also distribute | |||
other groups may also distribute working documents as Internet- | working documents as Internet-Drafts. The list of current Internet- | |||
Drafts. | 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." | |||
The list of current Internet-Drafts can be accessed at | This Internet-Draft will expire on October 6, 2011. | |||
http://www.ietf.org/ietf/1id-abstracts.txt. | ||||
The list of Internet-Draft Shadow Directories can be accessed at | ||||
http://www.ietf.org/shadow.html. | ||||
This Internet-Draft will expire on September 14, 2011. | ||||
Copyright Notice | Copyright Notice | |||
Copyright (c) 2011 IETF Trust and the persons identified as the | Copyright (c) 2011 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 | |||
described in the BSD License. | described in the Simplified BSD License. | |||
This document may contain material from IETF Documents or IETF | This document may contain material from IETF Documents or IETF | |||
Contributions published or made publicly available before November | Contributions published or made publicly available before November | |||
10, 2008. The person(s) controlling the copyright in some of this | 10, 2008. The person(s) controlling the copyright in some of this | |||
material may not have granted the IETF Trust the right to allow | material may not have granted the IETF Trust the right to allow | |||
modifications of such material outside the IETF Standards Process. | modifications of such material outside the IETF Standards Process. | |||
Without obtaining an adequate license from the person(s) controlling | Without obtaining an adequate license from the person(s) controlling | |||
the copyright in such materials, this document may not be modified | the copyright in such materials, this document may not be modified | |||
outside the IETF Standards Process, and derivative works of it may | outside the IETF Standards Process, and derivative works of it may | |||
not be created outside the IETF Standards Process, except to format | not be created outside the IETF Standards Process, except to format | |||
it for publication as an RFC or to translate it into languages other | it for publication as an RFC or to translate it into languages other | |||
than English. | than English. | |||
Table of Contents | Table of Contents | |||
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 8 | 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 9 | |||
1.1. Changes since RFC 3530 . . . . . . . . . . . . . . . . . 8 | 1.1. Changes since RFC 3530 . . . . . . . . . . . . . . . . . 9 | |||
1.2. Changes since RFC 3010 . . . . . . . . . . . . . . . . . 9 | 1.2. Changes since RFC 3010 . . . . . . . . . . . . . . . . . 10 | |||
1.3. NFS Version 4 Goals . . . . . . . . . . . . . . . . . . 10 | 1.3. NFS Version 4 Goals . . . . . . . . . . . . . . . . . . 11 | |||
1.4. Inconsistencies of this Document with the companion | 1.4. Inconsistencies of this Document with the companion | |||
document NFS Version 4 Protocol . . . . . . . . . . . . 10 | document NFS Version 4 Protocol . . . . . . . . . . . . 11 | |||
1.5. Overview of NFSv4 Features . . . . . . . . . . . . . . . 11 | 1.5. Overview of NFSv4 Features . . . . . . . . . . . . . . . 12 | |||
1.5.1. RPC and Security . . . . . . . . . . . . . . . . . . 11 | 1.5.1. RPC and Security . . . . . . . . . . . . . . . . . . 12 | |||
1.5.2. Procedure and Operation Structure . . . . . . . . . 11 | 1.5.2. Procedure and Operation Structure . . . . . . . . . 12 | |||
1.5.3. Filesystem Model . . . . . . . . . . . . . . . . . . 12 | 1.5.3. Filesystem Model . . . . . . . . . . . . . . . . . . 13 | |||
1.5.4. OPEN and CLOSE . . . . . . . . . . . . . . . . . . . 14 | 1.5.4. OPEN and CLOSE . . . . . . . . . . . . . . . . . . . 15 | |||
1.5.5. File Locking . . . . . . . . . . . . . . . . . . . . 14 | 1.5.5. File Locking . . . . . . . . . . . . . . . . . . . . 15 | |||
1.5.6. Client Caching and Delegation . . . . . . . . . . . 14 | 1.5.6. Client Caching and Delegation . . . . . . . . . . . 15 | |||
1.6. General Definitions . . . . . . . . . . . . . . . . . . 15 | 1.6. General Definitions . . . . . . . . . . . . . . . . . . 16 | |||
2. Protocol Data Types . . . . . . . . . . . . . . . . . . . . . 17 | 2. Protocol Data Types . . . . . . . . . . . . . . . . . . . . . 18 | |||
2.1. Basic Data Types . . . . . . . . . . . . . . . . . . . . 17 | 2.1. Basic Data Types . . . . . . . . . . . . . . . . . . . . 18 | |||
2.2. Structured Data Types . . . . . . . . . . . . . . . . . 19 | 2.2. Structured Data Types . . . . . . . . . . . . . . . . . 20 | |||
3. RPC and Security Flavor . . . . . . . . . . . . . . . . . . . 24 | 3. RPC and Security Flavor . . . . . . . . . . . . . . . . . . . 25 | |||
3.1. Ports and Transports . . . . . . . . . . . . . . . . . . 24 | 3.1. Ports and Transports . . . . . . . . . . . . . . . . . . 25 | |||
3.1.1. Client Retransmission Behavior . . . . . . . . . . . 25 | 3.1.1. Client Retransmission Behavior . . . . . . . . . . . 26 | |||
3.2. Security Flavors . . . . . . . . . . . . . . . . . . . . 26 | 3.2. Security Flavors . . . . . . . . . . . . . . . . . . . . 27 | |||
3.2.1. Security mechanisms for NFSv4 . . . . . . . . . . . 26 | 3.2.1. Security mechanisms for NFSv4 . . . . . . . . . . . 27 | |||
3.3. Security Negotiation . . . . . . . . . . . . . . . . . . 28 | 3.3. Security Negotiation . . . . . . . . . . . . . . . . . . 29 | |||
3.3.1. SECINFO . . . . . . . . . . . . . . . . . . . . . . 29 | 3.3.1. SECINFO . . . . . . . . . . . . . . . . . . . . . . 30 | |||
3.3.2. Security Error . . . . . . . . . . . . . . . . . . . 29 | 3.3.2. Security Error . . . . . . . . . . . . . . . . . . . 30 | |||
3.3.3. Callback RPC Authentication . . . . . . . . . . . . 29 | 3.3.3. Callback RPC Authentication . . . . . . . . . . . . 30 | |||
4. Filehandles . . . . . . . . . . . . . . . . . . . . . . . . . 31 | 4. Filehandles . . . . . . . . . . . . . . . . . . . . . . . . . 32 | |||
4.1. Obtaining the First Filehandle . . . . . . . . . . . . . 31 | 4.1. Obtaining the First Filehandle . . . . . . . . . . . . . 32 | |||
4.1.1. Root Filehandle . . . . . . . . . . . . . . . . . . 32 | 4.1.1. Root Filehandle . . . . . . . . . . . . . . . . . . 33 | |||
4.1.2. Public Filehandle . . . . . . . . . . . . . . . . . 32 | 4.1.2. Public Filehandle . . . . . . . . . . . . . . . . . 33 | |||
4.2. Filehandle Types . . . . . . . . . . . . . . . . . . . . 32 | 4.2. Filehandle Types . . . . . . . . . . . . . . . . . . . . 33 | |||
4.2.1. General Properties of a Filehandle . . . . . . . . . 33 | 4.2.1. General Properties of a Filehandle . . . . . . . . . 34 | |||
4.2.2. Persistent Filehandle . . . . . . . . . . . . . . . 33 | 4.2.2. Persistent Filehandle . . . . . . . . . . . . . . . 34 | |||
4.2.3. Volatile Filehandle . . . . . . . . . . . . . . . . 34 | 4.2.3. Volatile Filehandle . . . . . . . . . . . . . . . . 35 | |||
4.2.4. One Method of Constructing a Volatile Filehandle . . 35 | 4.2.4. One Method of Constructing a Volatile Filehandle . . 36 | |||
4.3. Client Recovery from Filehandle Expiration . . . . . . . 35 | 4.3. Client Recovery from Filehandle Expiration . . . . . . . 36 | |||
5. File Attributes . . . . . . . . . . . . . . . . . . . . . . . 36 | 5. File Attributes . . . . . . . . . . . . . . . . . . . . . . . 37 | |||
5.1. REQUIRED Attributes . . . . . . . . . . . . . . . . . . 37 | 5.1. REQUIRED Attributes . . . . . . . . . . . . . . . . . . 38 | |||
5.2. RECOMMENDED Attributes . . . . . . . . . . . . . . . . . 38 | 5.2. RECOMMENDED Attributes . . . . . . . . . . . . . . . . . 39 | |||
5.3. Named Attributes . . . . . . . . . . . . . . . . . . . . 38 | 5.3. Named Attributes . . . . . . . . . . . . . . . . . . . . 39 | |||
5.4. Classification of Attributes . . . . . . . . . . . . . . 40 | 5.4. Classification of Attributes . . . . . . . . . . . . . . 41 | |||
5.5. Set-Only and Get-Only Attributes . . . . . . . . . . . . 40 | 5.5. Set-Only and Get-Only Attributes . . . . . . . . . . . . 41 | |||
5.6. REQUIRED Attributes - List and Definition References . . 41 | 5.6. REQUIRED Attributes - List and Definition References . . 42 | |||
5.7. RECOMMENDED Attributes - List and Definition | 5.7. RECOMMENDED Attributes - List and Definition | |||
References . . . . . . . . . . . . . . . . . . . . . . . 42 | References . . . . . . . . . . . . . . . . . . . . . . . 43 | |||
5.8. Attribute Definitions . . . . . . . . . . . . . . . . . 43 | 5.8. Attribute Definitions . . . . . . . . . . . . . . . . . 44 | |||
5.8.1. Definitions of REQUIRED Attributes . . . . . . . . . 43 | 5.8.1. Definitions of REQUIRED Attributes . . . . . . . . . 44 | |||
5.8.2. Definitions of Uncategorized RECOMMENDED | 5.8.2. Definitions of Uncategorized RECOMMENDED | |||
Attributes . . . . . . . . . . . . . . . . . . . . . 45 | Attributes . . . . . . . . . . . . . . . . . . . . . 46 | |||
5.9. Interpreting owner and owner_group . . . . . . . . . . . 51 | 5.9. Interpreting owner and owner_group . . . . . . . . . . . 52 | |||
5.10. Character Case Attributes . . . . . . . . . . . . . . . 54 | 5.10. Character Case Attributes . . . . . . . . . . . . . . . 55 | |||
6. Access Control Attributes . . . . . . . . . . . . . . . . . . 54 | 6. Access Control Attributes . . . . . . . . . . . . . . . . . . 55 | |||
6.1. Goals . . . . . . . . . . . . . . . . . . . . . . . . . 54 | 6.1. Goals . . . . . . . . . . . . . . . . . . . . . . . . . 55 | |||
6.2. File Attributes Discussion . . . . . . . . . . . . . . . 55 | 6.2. File Attributes Discussion . . . . . . . . . . . . . . . 56 | |||
6.2.1. Attribute 12: acl . . . . . . . . . . . . . . . . . 55 | 6.2.1. Attribute 12: acl . . . . . . . . . . . . . . . . . 56 | |||
6.2.2. Attribute 33: mode . . . . . . . . . . . . . . . . . 69 | 6.2.2. Attribute 33: mode . . . . . . . . . . . . . . . . . 70 | |||
6.3. Common Methods . . . . . . . . . . . . . . . . . . . . . 70 | 6.3. Common Methods . . . . . . . . . . . . . . . . . . . . . 71 | |||
6.3.1. Interpreting an ACL . . . . . . . . . . . . . . . . 70 | 6.3.1. Interpreting an ACL . . . . . . . . . . . . . . . . 71 | |||
6.3.2. Computing a Mode Attribute from an ACL . . . . . . . 71 | 6.3.2. Computing a Mode Attribute from an ACL . . . . . . . 72 | |||
6.4. Requirements . . . . . . . . . . . . . . . . . . . . . . 72 | 6.4. Requirements . . . . . . . . . . . . . . . . . . . . . . 73 | |||
6.4.1. Setting the mode and/or ACL Attributes . . . . . . . 72 | 6.4.1. Setting the mode and/or ACL Attributes . . . . . . . 73 | |||
6.4.2. Retrieving the mode and/or ACL Attributes . . . . . 74 | 6.4.2. Retrieving the mode and/or ACL Attributes . . . . . 75 | |||
6.4.3. Creating New Objects . . . . . . . . . . . . . . . . 74 | 6.4.3. Creating New Objects . . . . . . . . . . . . . . . . 75 | |||
7. Multi-Server Namespace . . . . . . . . . . . . . . . . . . . 76 | 7. Multi-Server Namespace . . . . . . . . . . . . . . . . . . . 77 | |||
7.1. Location Attributes . . . . . . . . . . . . . . . . . . 76 | 7.1. Location Attributes . . . . . . . . . . . . . . . . . . 77 | |||
7.2. File System Presence or Absence . . . . . . . . . . . . 76 | 7.2. File System Presence or Absence . . . . . . . . . . . . 77 | |||
7.3. Getting Attributes for an Absent File System . . . . . . 77 | 7.3. Getting Attributes for an Absent File System . . . . . . 78 | |||
7.3.1. GETATTR Within an Absent File System . . . . . . . . 78 | 7.3.1. GETATTR Within an Absent File System . . . . . . . . 79 | |||
7.3.2. READDIR and Absent File Systems . . . . . . . . . . 79 | 7.3.2. READDIR and Absent File Systems . . . . . . . . . . 80 | |||
7.4. Uses of Location Information . . . . . . . . . . . . . . 79 | 7.4. Uses of Location Information . . . . . . . . . . . . . . 80 | |||
7.4.1. File System Replication . . . . . . . . . . . . . . 80 | 7.4.1. File System Replication . . . . . . . . . . . . . . 81 | |||
7.4.2. File System Migration . . . . . . . . . . . . . . . 81 | 7.4.2. File System Migration . . . . . . . . . . . . . . . 82 | |||
7.4.3. Referrals . . . . . . . . . . . . . . . . . . . . . 81 | 7.4.3. Referrals . . . . . . . . . . . . . . . . . . . . . 82 | |||
7.5. Location Entries and Server Identity . . . . . . . . . . 82 | 7.5. Location Entries and Server Identity . . . . . . . . . . 83 | |||
7.6. Additional Client-Side Considerations . . . . . . . . . 83 | 7.6. Additional Client-Side Considerations . . . . . . . . . 84 | |||
7.7. Effecting File System Transitions . . . . . . . . . . . 84 | 7.7. Effecting File System Transitions . . . . . . . . . . . 85 | |||
7.7.1. File System Transitions and Simultaneous Access . . 85 | 7.7.1. File System Transitions and Simultaneous Access . . 86 | |||
7.7.2. Filehandles and File System Transitions . . . . . . 85 | 7.7.2. Filehandles and File System Transitions . . . . . . 86 | |||
7.7.3. Fileids and File System Transitions . . . . . . . . 86 | 7.7.3. Fileids and File System Transitions . . . . . . . . 87 | |||
7.7.4. Fsids and File System Transitions . . . . . . . . . 87 | 7.7.4. Fsids and File System Transitions . . . . . . . . . 88 | |||
7.7.5. The Change Attribute and File System Transitions . . 87 | 7.7.5. The Change Attribute and File System Transitions . . 88 | |||
7.7.6. Lock State and File System Transitions . . . . . . . 88 | 7.7.6. Lock State and File System Transitions . . . . . . . 89 | |||
7.7.7. Write Verifiers and File System Transitions . . . . 90 | 7.7.7. Write Verifiers and File System Transitions . . . . 91 | |||
7.7.8. Readdir Cookies and Verifiers and File System | 7.7.8. Readdir Cookies and Verifiers and File System | |||
Transitions . . . . . . . . . . . . . . . . . . . . 90 | Transitions . . . . . . . . . . . . . . . . . . . . 91 | |||
7.7.9. File System Data and File System Transitions . . . . 90 | 7.7.9. File System Data and File System Transitions . . . . 91 | |||
7.8. Effecting File System Referrals . . . . . . . . . . . . 92 | 7.8. Effecting File System Referrals . . . . . . . . . . . . 93 | |||
7.8.1. Referral Example (LOOKUP) . . . . . . . . . . . . . 92 | 7.8.1. Referral Example (LOOKUP) . . . . . . . . . . . . . 93 | |||
7.8.2. Referral Example (READDIR) . . . . . . . . . . . . . 96 | 7.8.2. Referral Example (READDIR) . . . . . . . . . . . . . 97 | |||
7.9. The Attribute fs_locations . . . . . . . . . . . . . . . 98 | 7.9. The Attribute fs_locations . . . . . . . . . . . . . . . 99 | |||
7.9.1. Inferring Transition Modes . . . . . . . . . . . . . 100 | 7.9.1. Inferring Transition Modes . . . . . . . . . . . . . 101 | |||
8. NFS Server Name Space . . . . . . . . . . . . . . . . . . . . 101 | 8. NFS Server Name Space . . . . . . . . . . . . . . . . . . . . 102 | |||
8.1. Server Exports . . . . . . . . . . . . . . . . . . . . . 102 | 8.1. Server Exports . . . . . . . . . . . . . . . . . . . . . 103 | |||
8.2. Browsing Exports . . . . . . . . . . . . . . . . . . . . 102 | 8.2. Browsing Exports . . . . . . . . . . . . . . . . . . . . 103 | |||
8.3. Server Pseudo Filesystem . . . . . . . . . . . . . . . . 102 | 8.3. Server Pseudo Filesystem . . . . . . . . . . . . . . . . 103 | |||
8.4. Multiple Roots . . . . . . . . . . . . . . . . . . . . . 103 | 8.4. Multiple Roots . . . . . . . . . . . . . . . . . . . . . 104 | |||
8.5. Filehandle Volatility . . . . . . . . . . . . . . . . . 103 | 8.5. Filehandle Volatility . . . . . . . . . . . . . . . . . 104 | |||
8.6. Exported Root . . . . . . . . . . . . . . . . . . . . . 103 | 8.6. Exported Root . . . . . . . . . . . . . . . . . . . . . 104 | |||
8.7. Mount Point Crossing . . . . . . . . . . . . . . . . . . 104 | 8.7. Mount Point Crossing . . . . . . . . . . . . . . . . . . 105 | |||
8.8. Security Policy and Name Space Presentation . . . . . . 104 | 8.8. Security Policy and Name Space Presentation . . . . . . 105 | |||
9. File Locking and Share Reservations . . . . . . . . . . . . . 105 | 9. File Locking and Share Reservations . . . . . . . . . . . . . 106 | |||
9.1. Opens and Byte-Range Locks . . . . . . . . . . . . . . . 106 | 9.1. Opens and Byte-Range Locks . . . . . . . . . . . . . . . 107 | |||
9.1.1. Client ID . . . . . . . . . . . . . . . . . . . . . 106 | 9.1.1. Client ID . . . . . . . . . . . . . . . . . . . . . 107 | |||
9.1.2. Server Release of Client ID . . . . . . . . . . . . 109 | 9.1.2. Server Release of Client ID . . . . . . . . . . . . 110 | |||
9.1.3. Stateid Definition . . . . . . . . . . . . . . . . . 110 | 9.1.3. Stateid Definition . . . . . . . . . . . . . . . . . 111 | |||
9.1.4. lock_owner . . . . . . . . . . . . . . . . . . . . . 117 | 9.1.4. lock-owner . . . . . . . . . . . . . . . . . . . . . 118 | |||
9.1.5. Use of the Stateid and Locking . . . . . . . . . . . 118 | 9.1.5. Use of the Stateid and Locking . . . . . . . . . . . 119 | |||
9.1.6. Sequencing of Lock Requests . . . . . . . . . . . . 120 | 9.1.6. Sequencing of Lock Requests . . . . . . . . . . . . 121 | |||
9.1.7. Recovery from Replayed Requests . . . . . . . . . . 121 | 9.1.7. Recovery from Replayed Requests . . . . . . . . . . 122 | |||
9.1.8. Releasing lock_owner State . . . . . . . . . . . . . 121 | 9.1.8. Releasing lock-owner State . . . . . . . . . . . . . 122 | |||
9.1.9. Use of Open Confirmation . . . . . . . . . . . . . . 122 | 9.1.9. Use of Open Confirmation . . . . . . . . . . . . . . 123 | |||
9.2. Lock Ranges . . . . . . . . . . . . . . . . . . . . . . 123 | 9.2. Lock Ranges . . . . . . . . . . . . . . . . . . . . . . 124 | |||
9.3. Upgrading and Downgrading Locks . . . . . . . . . . . . 123 | 9.3. Upgrading and Downgrading Locks . . . . . . . . . . . . 124 | |||
9.4. Blocking Locks . . . . . . . . . . . . . . . . . . . . . 124 | 9.4. Blocking Locks . . . . . . . . . . . . . . . . . . . . . 125 | |||
9.5. Lease Renewal . . . . . . . . . . . . . . . . . . . . . 125 | 9.5. Lease Renewal . . . . . . . . . . . . . . . . . . . . . 126 | |||
9.6. Crash Recovery . . . . . . . . . . . . . . . . . . . . . 126 | 9.6. Crash Recovery . . . . . . . . . . . . . . . . . . . . . 126 | |||
9.6.1. Client Failure and Recovery . . . . . . . . . . . . 126 | 9.6.1. Client Failure and Recovery . . . . . . . . . . . . 127 | |||
9.6.2. Server Failure and Recovery . . . . . . . . . . . . 127 | 9.6.2. Server Failure and Recovery . . . . . . . . . . . . 127 | |||
9.6.3. Network Partitions and Recovery . . . . . . . . . . 128 | 9.6.3. Network Partitions and Recovery . . . . . . . . . . 129 | |||
9.7. Recovery from a Lock Request Timeout or Abort . . . . . 135 | 9.7. Recovery from a Lock Request Timeout or Abort . . . . . 136 | |||
9.8. Server Revocation of Locks . . . . . . . . . . . . . . . 135 | 9.8. Server Revocation of Locks . . . . . . . . . . . . . . . 136 | |||
9.9. Share Reservations . . . . . . . . . . . . . . . . . . . 137 | 9.9. Share Reservations . . . . . . . . . . . . . . . . . . . 137 | |||
9.10. OPEN/CLOSE Operations . . . . . . . . . . . . . . . . . 137 | 9.10. OPEN/CLOSE Operations . . . . . . . . . . . . . . . . . 138 | |||
9.10.1. Close and Retention of State Information . . . . . . 138 | 9.10.1. Close and Retention of State Information . . . . . . 139 | |||
9.11. Open Upgrade and Downgrade . . . . . . . . . . . . . . . 139 | 9.11. Open Upgrade and Downgrade . . . . . . . . . . . . . . . 139 | |||
9.12. Short and Long Leases . . . . . . . . . . . . . . . . . 139 | 9.12. Short and Long Leases . . . . . . . . . . . . . . . . . 140 | |||
9.13. Clocks, Propagation Delay, and Calculating Lease | 9.13. Clocks, Propagation Delay, and Calculating Lease | |||
Expiration . . . . . . . . . . . . . . . . . . . . . . . 140 | Expiration . . . . . . . . . . . . . . . . . . . . . . . 141 | |||
9.14. Migration, Replication and State . . . . . . . . . . . . 140 | 9.14. Migration, Replication and State . . . . . . . . . . . . 141 | |||
9.14.1. Migration and State . . . . . . . . . . . . . . . . 141 | 9.14.1. Migration and State . . . . . . . . . . . . . . . . 142 | |||
9.14.2. Replication and State . . . . . . . . . . . . . . . 142 | 9.14.2. Replication and State . . . . . . . . . . . . . . . 142 | |||
9.14.3. Notification of Migrated Lease . . . . . . . . . . . 142 | 9.14.3. Notification of Migrated Lease . . . . . . . . . . . 143 | |||
9.14.4. Migration and the Lease_time Attribute . . . . . . . 143 | 9.14.4. Migration and the Lease_time Attribute . . . . . . . 144 | |||
10. Client-Side Caching . . . . . . . . . . . . . . . . . . . . . 143 | 10. Client-Side Caching . . . . . . . . . . . . . . . . . . . . . 144 | |||
10.1. Performance Challenges for Client-Side Caching . . . . . 144 | 10.1. Performance Challenges for Client-Side Caching . . . . . 145 | |||
10.2. Delegation and Callbacks . . . . . . . . . . . . . . . . 145 | 10.2. Delegation and Callbacks . . . . . . . . . . . . . . . . 146 | |||
10.2.1. Delegation Recovery . . . . . . . . . . . . . . . . 147 | 10.2.1. Delegation Recovery . . . . . . . . . . . . . . . . 147 | |||
10.3. Data Caching . . . . . . . . . . . . . . . . . . . . . . 149 | 10.3. Data Caching . . . . . . . . . . . . . . . . . . . . . . 149 | |||
10.3.1. Data Caching and OPENs . . . . . . . . . . . . . . . 149 | 10.3.1. Data Caching and OPENs . . . . . . . . . . . . . . . 150 | |||
10.3.2. Data Caching and File Locking . . . . . . . . . . . 150 | 10.3.2. Data Caching and File Locking . . . . . . . . . . . 151 | |||
10.3.3. Data Caching and Mandatory File Locking . . . . . . 151 | 10.3.3. Data Caching and Mandatory File Locking . . . . . . 152 | |||
10.3.4. Data Caching and File Identity . . . . . . . . . . . 152 | 10.3.4. Data Caching and File Identity . . . . . . . . . . . 153 | |||
10.4. Open Delegation . . . . . . . . . . . . . . . . . . . . 153 | 10.4. Open Delegation . . . . . . . . . . . . . . . . . . . . 154 | |||
10.4.1. Open Delegation and Data Caching . . . . . . . . . . 155 | 10.4.1. Open Delegation and Data Caching . . . . . . . . . . 156 | |||
10.4.2. Open Delegation and File Locks . . . . . . . . . . . 157 | 10.4.2. Open Delegation and File Locks . . . . . . . . . . . 158 | |||
10.4.3. Handling of CB_GETATTR . . . . . . . . . . . . . . . 157 | 10.4.3. Handling of CB_GETATTR . . . . . . . . . . . . . . . 158 | |||
10.4.4. Recall of Open Delegation . . . . . . . . . . . . . 160 | 10.4.4. Recall of Open Delegation . . . . . . . . . . . . . 161 | |||
10.4.5. OPEN Delegation Race with CB_RECALL . . . . . . . . 162 | 10.4.5. OPEN Delegation Race with CB_RECALL . . . . . . . . 163 | |||
10.4.6. Clients that Fail to Honor Delegation Recalls . . . 163 | 10.4.6. Clients that Fail to Honor Delegation Recalls . . . 164 | |||
10.4.7. Delegation Revocation . . . . . . . . . . . . . . . 164 | 10.4.7. Delegation Revocation . . . . . . . . . . . . . . . 165 | |||
10.5. Data Caching and Revocation . . . . . . . . . . . . . . 164 | 10.5. Data Caching and Revocation . . . . . . . . . . . . . . 165 | |||
10.5.1. Revocation Recovery for Write Open Delegation . . . 165 | 10.5.1. Revocation Recovery for Write Open Delegation . . . 166 | |||
10.6. Attribute Caching . . . . . . . . . . . . . . . . . . . 165 | 10.6. Attribute Caching . . . . . . . . . . . . . . . . . . . 166 | |||
10.7. Data and Metadata Caching and Memory Mapped Files . . . 167 | 10.7. Data and Metadata Caching and Memory Mapped Files . . . 168 | |||
10.8. Name Caching . . . . . . . . . . . . . . . . . . . . . . 169 | 10.8. Name Caching . . . . . . . . . . . . . . . . . . . . . . 170 | |||
10.9. Directory Caching . . . . . . . . . . . . . . . . . . . 170 | 10.9. Directory Caching . . . . . . . . . . . . . . . . . . . 171 | |||
11. Minor Versioning . . . . . . . . . . . . . . . . . . . . . . 171 | 11. Minor Versioning . . . . . . . . . . . . . . . . . . . . . . 172 | |||
12. Internationalization . . . . . . . . . . . . . . . . . . . . 174 | 12. Internationalization . . . . . . . . . . . . . . . . . . . . 175 | |||
12.1. Use of UTF-8 . . . . . . . . . . . . . . . . . . . . . . 175 | 12.1. Use of UTF-8 . . . . . . . . . . . . . . . . . . . . . . 176 | |||
12.1.1. Relation to Stringprep . . . . . . . . . . . . . . . 175 | 12.1.1. Relation to Stringprep . . . . . . . . . . . . . . . 176 | |||
12.1.2. Normalization, Equivalence, and Confusability . . . 176 | 12.1.2. Normalization, Equivalence, and Confusability . . . 177 | |||
12.2. String Type Overview . . . . . . . . . . . . . . . . . . 179 | 12.2. String Type Overview . . . . . . . . . . . . . . . . . . 180 | |||
12.2.1. Overall String Class Divisions . . . . . . . . . . . 179 | 12.2.1. Overall String Class Divisions . . . . . . . . . . . 180 | |||
12.2.2. Divisions by Typedef Parent types . . . . . . . . . 180 | 12.2.2. Divisions by Typedef Parent types . . . . . . . . . 181 | |||
12.2.3. Individual Types and Their Handling . . . . . . . . 181 | 12.2.3. Individual Types and Their Handling . . . . . . . . 182 | |||
12.3. Errors Related to Strings . . . . . . . . . . . . . . . 182 | 12.3. Errors Related to Strings . . . . . . . . . . . . . . . 183 | |||
12.4. Types with Pre-processing to Resolve Mixture Issues . . 183 | 12.4. Types with Pre-processing to Resolve Mixture Issues . . 184 | |||
12.4.1. Processing of Principal Strings . . . . . . . . . . 183 | 12.4.1. Processing of Principal Strings . . . . . . . . . . 184 | |||
12.4.2. Processing of Server Id Strings . . . . . . . . . . 183 | 12.4.2. Processing of Server Id Strings . . . . . . . . . . 184 | |||
12.5. String Types without Internationalization Processing . . 184 | 12.5. String Types without Internationalization Processing . . 185 | |||
12.6. Types with Processing Defined by Other Internet Areas . 184 | 12.6. Types with Processing Defined by Other Internet Areas . 185 | |||
12.7. String Types with NFS-specific Processing . . . . . . . 185 | 12.7. String Types with NFS-specific Processing . . . . . . . 186 | |||
12.7.1. Handling of File Name Components . . . . . . . . . . 186 | 12.7.1. Handling of File Name Components . . . . . . . . . . 187 | |||
12.7.2. Processing of Link Text . . . . . . . . . . . . . . 195 | 12.7.2. Processing of Link Text . . . . . . . . . . . . . . 196 | |||
12.7.3. Processing of Principal Prefixes . . . . . . . . . . 196 | 12.7.3. Processing of Principal Prefixes . . . . . . . . . . 197 | |||
13. Error Values . . . . . . . . . . . . . . . . . . . . . . . . 197 | 13. Error Values . . . . . . . . . . . . . . . . . . . . . . . . 198 | |||
13.1. Error Definitions . . . . . . . . . . . . . . . . . . . 197 | 13.1. Error Definitions . . . . . . . . . . . . . . . . . . . 198 | |||
13.1.1. General Errors . . . . . . . . . . . . . . . . . . . 199 | 13.1.1. General Errors . . . . . . . . . . . . . . . . . . . 200 | |||
13.1.2. Filehandle Errors . . . . . . . . . . . . . . . . . 200 | 13.1.2. Filehandle Errors . . . . . . . . . . . . . . . . . 201 | |||
13.1.3. Compound Structure Errors . . . . . . . . . . . . . 201 | 13.1.3. Compound Structure Errors . . . . . . . . . . . . . 202 | |||
13.1.4. File System Errors . . . . . . . . . . . . . . . . . 202 | 13.1.4. File System Errors . . . . . . . . . . . . . . . . . 203 | |||
13.1.5. State Management Errors . . . . . . . . . . . . . . 204 | 13.1.5. State Management Errors . . . . . . . . . . . . . . 205 | |||
13.1.6. Security Errors . . . . . . . . . . . . . . . . . . 205 | 13.1.6. Security Errors . . . . . . . . . . . . . . . . . . 206 | |||
13.1.7. Name Errors . . . . . . . . . . . . . . . . . . . . 205 | 13.1.7. Name Errors . . . . . . . . . . . . . . . . . . . . 206 | |||
13.1.8. Locking Errors . . . . . . . . . . . . . . . . . . . 206 | 13.1.8. Locking Errors . . . . . . . . . . . . . . . . . . . 207 | |||
13.1.9. Reclaim Errors . . . . . . . . . . . . . . . . . . . 207 | 13.1.9. Reclaim Errors . . . . . . . . . . . . . . . . . . . 208 | |||
13.1.10. Client Management Errors . . . . . . . . . . . . . . 208 | 13.1.10. Client Management Errors . . . . . . . . . . . . . . 209 | |||
13.1.11. Attribute Handling Errors . . . . . . . . . . . . . 208 | 13.1.11. Attribute Handling Errors . . . . . . . . . . . . . 209 | |||
13.2. Operations and their valid errors . . . . . . . . . . . 209 | 13.2. Operations and their valid errors . . . . . . . . . . . 210 | |||
13.3. Callback operations and their valid errors . . . . . . . 216 | 13.3. Callback operations and their valid errors . . . . . . . 217 | |||
13.4. Errors and the operations that use them . . . . . . . . 216 | 13.4. Errors and the operations that use them . . . . . . . . 217 | |||
14. NFSv4 Requests . . . . . . . . . . . . . . . . . . . . . . . 221 | 14. NFSv4 Requests . . . . . . . . . . . . . . . . . . . . . . . 222 | |||
14.1. Compound Procedure . . . . . . . . . . . . . . . . . . . 221 | 14.1. Compound Procedure . . . . . . . . . . . . . . . . . . . 222 | |||
14.2. Evaluation of a Compound Request . . . . . . . . . . . . 222 | 14.2. Evaluation of a Compound Request . . . . . . . . . . . . 223 | |||
14.3. Synchronous Modifying Operations . . . . . . . . . . . . 223 | 14.3. Synchronous Modifying Operations . . . . . . . . . . . . 224 | |||
14.4. Operation Values . . . . . . . . . . . . . . . . . . . . 223 | 14.4. Operation Values . . . . . . . . . . . . . . . . . . . . 224 | |||
15. NFSv4 Procedures . . . . . . . . . . . . . . . . . . . . . . 223 | 15. NFSv4 Procedures . . . . . . . . . . . . . . . . . . . . . . 224 | |||
15.1. Procedure 0: NULL - No Operation . . . . . . . . . . . . 223 | 15.1. Procedure 0: NULL - No Operation . . . . . . . . . . . . 224 | |||
15.2. Procedure 1: COMPOUND - Compound Operations . . . . . . 224 | 15.2. Procedure 1: COMPOUND - Compound Operations . . . . . . 225 | |||
15.3. Operation 3: ACCESS - Check Access Rights . . . . . . . 229 | 15.3. Operation 3: ACCESS - Check Access Rights . . . . . . . 230 | |||
15.4. Operation 4: CLOSE - Close File . . . . . . . . . . . . 232 | 15.4. Operation 4: CLOSE - Close File . . . . . . . . . . . . 233 | |||
15.5. Operation 5: COMMIT - Commit Cached Data . . . . . . . . 233 | 15.5. Operation 5: COMMIT - Commit Cached Data . . . . . . . . 234 | |||
15.6. Operation 6: CREATE - Create a Non-Regular File Object . 235 | 15.6. Operation 6: CREATE - Create a Non-Regular File Object . 236 | |||
15.7. Operation 7: DELEGPURGE - Purge Delegations Awaiting | 15.7. Operation 7: DELEGPURGE - Purge Delegations Awaiting | |||
Recovery . . . . . . . . . . . . . . . . . . . . . . . . 238 | Recovery . . . . . . . . . . . . . . . . . . . . . . . . 239 | |||
15.8. Operation 8: DELEGRETURN - Return Delegation . . . . . . 239 | 15.8. Operation 8: DELEGRETURN - Return Delegation . . . . . . 240 | |||
15.9. Operation 9: GETATTR - Get Attributes . . . . . . . . . 239 | 15.9. Operation 9: GETATTR - Get Attributes . . . . . . . . . 240 | |||
15.10. Operation 10: GETFH - Get Current Filehandle . . . . . . 241 | 15.10. Operation 10: GETFH - Get Current Filehandle . . . . . . 242 | |||
15.11. Operation 11: LINK - Create Link to a File . . . . . . . 242 | 15.11. Operation 11: LINK - Create Link to a File . . . . . . . 243 | |||
15.12. Operation 12: LOCK - Create Lock . . . . . . . . . . . . 243 | 15.12. Operation 12: LOCK - Create Lock . . . . . . . . . . . . 244 | |||
15.13. Operation 13: LOCKT - Test For Lock . . . . . . . . . . 247 | 15.13. Operation 13: LOCKT - Test For Lock . . . . . . . . . . 248 | |||
15.14. Operation 14: LOCKU - Unlock File . . . . . . . . . . . 249 | 15.14. Operation 14: LOCKU - Unlock File . . . . . . . . . . . 250 | |||
15.15. Operation 15: LOOKUP - Lookup Filename . . . . . . . . . 250 | 15.15. Operation 15: LOOKUP - Lookup Filename . . . . . . . . . 251 | |||
15.16. Operation 16: LOOKUPP - Lookup Parent Directory . . . . 252 | 15.16. Operation 16: LOOKUPP - Lookup Parent Directory . . . . 253 | |||
15.17. Operation 17: NVERIFY - Verify Difference in | 15.17. Operation 17: NVERIFY - Verify Difference in | |||
Attributes . . . . . . . . . . . . . . . . . . . . . . . 252 | Attributes . . . . . . . . . . . . . . . . . . . . . . . 253 | |||
15.18. Operation 18: OPEN - Open a Regular File . . . . . . . . 254 | 15.18. Operation 18: OPEN - Open a Regular File . . . . . . . . 255 | |||
15.19. Operation 19: OPENATTR - Open Named Attribute | 15.19. Operation 19: OPENATTR - Open Named Attribute | |||
Directory . . . . . . . . . . . . . . . . . . . . . . . 264 | Directory . . . . . . . . . . . . . . . . . . . . . . . 265 | |||
15.20. Operation 20: OPEN_CONFIRM - Confirm Open . . . . . . . 265 | 15.20. Operation 20: OPEN_CONFIRM - Confirm Open . . . . . . . 266 | |||
15.21. Operation 21: OPEN_DOWNGRADE - Reduce Open File Access . 267 | 15.21. Operation 21: OPEN_DOWNGRADE - Reduce Open File Access . 268 | |||
15.22. Operation 22: PUTFH - Set Current Filehandle . . . . . . 268 | 15.22. Operation 22: PUTFH - Set Current Filehandle . . . . . . 269 | |||
15.23. Operation 23: PUTPUBFH - Set Public Filehandle . . . . . 269 | 15.23. Operation 23: PUTPUBFH - Set Public Filehandle . . . . . 270 | |||
15.24. Operation 24: PUTROOTFH - Set Root Filehandle . . . . . 270 | 15.24. Operation 24: PUTROOTFH - Set Root Filehandle . . . . . 271 | |||
15.25. Operation 25: READ - Read from File . . . . . . . . . . 271 | 15.25. Operation 25: READ - Read from File . . . . . . . . . . 272 | |||
15.26. Operation 26: READDIR - Read Directory . . . . . . . . . 273 | 15.26. Operation 26: READDIR - Read Directory . . . . . . . . . 274 | |||
15.27. Operation 27: READLINK - Read Symbolic Link . . . . . . 277 | 15.27. Operation 27: READLINK - Read Symbolic Link . . . . . . 278 | |||
15.28. Operation 28: REMOVE - Remove Filesystem Object . . . . 278 | 15.28. Operation 28: REMOVE - Remove Filesystem Object . . . . 279 | |||
15.29. Operation 29: RENAME - Rename Directory Entry . . . . . 280 | 15.29. Operation 29: RENAME - Rename Directory Entry . . . . . 281 | |||
15.30. Operation 30: RENEW - Renew a Lease . . . . . . . . . . 282 | 15.30. Operation 30: RENEW - Renew a Lease . . . . . . . . . . 283 | |||
15.31. Operation 31: RESTOREFH - Restore Saved Filehandle . . . 283 | 15.31. Operation 31: RESTOREFH - Restore Saved Filehandle . . . 284 | |||
15.32. Operation 32: SAVEFH - Save Current Filehandle . . . . . 284 | 15.32. Operation 32: SAVEFH - Save Current Filehandle . . . . . 285 | |||
15.33. Operation 33: SECINFO - Obtain Available Security . . . 284 | 15.33. Operation 33: SECINFO - Obtain Available Security . . . 285 | |||
15.34. Operation 34: SETATTR - Set Attributes . . . . . . . . . 287 | 15.34. Operation 34: SETATTR - Set Attributes . . . . . . . . . 288 | |||
15.35. Operation 35: SETCLIENTID - Negotiate Client ID . . . . 290 | 15.35. Operation 35: SETCLIENTID - Negotiate Client ID . . . . 291 | |||
15.36. Operation 36: SETCLIENTID_CONFIRM - Confirm Client ID . 294 | 15.36. Operation 36: SETCLIENTID_CONFIRM - Confirm Client ID . 295 | |||
15.37. Operation 37: VERIFY - Verify Same Attributes . . . . . 297 | 15.37. Operation 37: VERIFY - Verify Same Attributes . . . . . 298 | |||
15.38. Operation 38: WRITE - Write to File . . . . . . . . . . 299 | 15.38. Operation 38: WRITE - Write to File . . . . . . . . . . 300 | |||
15.39. Operation 39: RELEASE_LOCKOWNER - Release Lockowner | 15.39. Operation 39: RELEASE_LOCKOWNER - Release Lockowner | |||
State . . . . . . . . . . . . . . . . . . . . . . . . . 303 | State . . . . . . . . . . . . . . . . . . . . . . . . . 304 | |||
15.40. Operation 10044: ILLEGAL - Illegal operation . . . . . . 304 | 15.40. Operation 10044: ILLEGAL - Illegal operation . . . . . . 305 | |||
16. NFSv4 Callback Procedures . . . . . . . . . . . . . . . . . . 304 | 16. NFSv4 Callback Procedures . . . . . . . . . . . . . . . . . . 305 | |||
16.1. Procedure 0: CB_NULL - No Operation . . . . . . . . . . 305 | 16.1. Procedure 0: CB_NULL - No Operation . . . . . . . . . . 306 | |||
16.2. Procedure 1: CB_COMPOUND - Compound Operations . . . . . 305 | 16.2. Procedure 1: CB_COMPOUND - Compound Operations . . . . . 306 | |||
16.2.6. Operation 3: CB_GETATTR - Get Attributes . . . . . . 307 | 16.2.6. Operation 3: CB_GETATTR - Get Attributes . . . . . . 308 | |||
16.2.7. Operation 4: CB_RECALL - Recall an Open Delegation . 308 | 16.2.7. Operation 4: CB_RECALL - Recall an Open Delegation . 309 | |||
16.2.8. Operation 10044: CB_ILLEGAL - Illegal Callback | 16.2.8. Operation 10044: CB_ILLEGAL - Illegal Callback | |||
Operation . . . . . . . . . . . . . . . . . . . . . 309 | Operation . . . . . . . . . . . . . . . . . . . . . 310 | |||
17. Security Considerations . . . . . . . . . . . . . . . . . . . 310 | 17. Security Considerations . . . . . . . . . . . . . . . . . . . 311 | |||
18. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 311 | 18. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 312 | |||
18.1. Named Attribute Definitions . . . . . . . . . . . . . . 311 | 18.1. Named Attribute Definitions . . . . . . . . . . . . . . 312 | |||
18.1.1. Initial Registry . . . . . . . . . . . . . . . . . . 312 | 18.1.1. Initial Registry . . . . . . . . . . . . . . . . . . 313 | |||
18.1.2. Updating Registrations . . . . . . . . . . . . . . . 312 | 18.1.2. Updating Registrations . . . . . . . . . . . . . . . 313 | |||
18.2. ONC RPC Network Identifiers (netids) . . . . . . . . . . 312 | 18.2. ONC RPC Network Identifiers (netids) . . . . . . . . . . 313 | |||
18.2.1. Initial Registry . . . . . . . . . . . . . . . . . . 314 | 18.2.1. Initial Registry . . . . . . . . . . . . . . . . . . 315 | |||
18.2.2. Updating Registrations . . . . . . . . . . . . . . . 314 | 18.2.2. Updating Registrations . . . . . . . . . . . . . . . 315 | |||
19. References . . . . . . . . . . . . . . . . . . . . . . . . . 314 | 19. References . . . . . . . . . . . . . . . . . . . . . . . . . 315 | |||
19.1. Normative References . . . . . . . . . . . . . . . . . . 314 | 19.1. Normative References . . . . . . . . . . . . . . . . . . 315 | |||
19.2. Informative References . . . . . . . . . . . . . . . . . 315 | 19.2. Informative References . . . . . . . . . . . . . . . . . 316 | |||
Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 317 | Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 318 | |||
Appendix B. RFC Editor Notes . . . . . . . . . . . . . . . . . . 318 | Appendix B. RFC Editor Notes . . . . . . . . . . . . . . . . . . 319 | |||
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 318 | Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 319 | |||
1. Introduction | 1. Introduction | |||
1.1. Changes since RFC 3530 | 1.1. Changes since RFC 3530 | |||
This document, together with the companion XDR description document | This document, together with the companion XDR description document | |||
[2], obsoletes RFC 3530 [11] as the authoritative document describing | [2], obsoletes RFC 3530 [11] as the authoritative document describing | |||
NFSv4. It does not introduce any over-the-wire protocol changes, in | NFSv4. It does not introduce any over-the-wire protocol changes, in | |||
the sense that previously valid requests requests remain valid. | the sense that previously valid requests requests remain valid. | |||
However, some requests previously defined as invalid, although not | However, some requests previously defined as invalid, although not | |||
skipping to change at page 21, line 41 | skipping to change at page 21, line 41 | |||
uint64_t major; | uint64_t major; | |||
uint64_t minor; | uint64_t minor; | |||
}; | }; | |||
This type is the filesystem identifier that is used as a mandatory | This type is the filesystem identifier that is used as a mandatory | |||
attribute. | attribute. | |||
2.2.6. fs_location4 | 2.2.6. fs_location4 | |||
struct fs_location4 { | struct fs_location4 { | |||
utf8must server<>; | utf8val_must server<>; | |||
pathname4 rootpath; | pathname4 rootpath; | |||
}; | }; | |||
2.2.7. fs_locations4 | 2.2.7. fs_locations4 | |||
struct fs_locations4 { | struct fs_locations4 { | |||
pathname4 fs_root; | pathname4 fs_root; | |||
fs_location4 locations<>; | fs_location4 locations<>; | |||
}; | }; | |||
skipping to change at page 56, line 48 | skipping to change at page 56, line 48 | |||
typedef uint32_t acetype4; | typedef uint32_t acetype4; | |||
typedef uint32_t aceflag4; | typedef uint32_t aceflag4; | |||
typedef uint32_t acemask4; | typedef uint32_t acemask4; | |||
struct nfsace4 { | struct nfsace4 { | |||
acetype4 type; | acetype4 type; | |||
aceflag4 flag; | aceflag4 flag; | |||
acemask4 access_mask; | acemask4 access_mask; | |||
utf8_must who; | utf8val_must who; | |||
}; | }; | |||
To determine if a request succeeds, the server processes each nfsace4 | To determine if a request succeeds, the server processes each nfsace4 | |||
entry in order. Only ACEs which have a "who" that matches the | entry in order. Only ACEs which have a "who" that matches the | |||
requester are considered. Each ACE is processed until all of the | requester are considered. Each ACE is processed until all of the | |||
bits of the requester's access have been ALLOWED. Once a bit (see | bits of the requester's access have been ALLOWED. Once a bit (see | |||
below) has been ALLOWED by an ACCESS_ALLOWED_ACE, it is no longer | below) has been ALLOWED by an ACCESS_ALLOWED_ACE, it is no longer | |||
considered in the processing of later ACEs. If an ACCESS_DENIED_ACE | considered in the processing of later ACEs. If an ACCESS_DENIED_ACE | |||
is encountered where the requester's access still has unALLOWED bits | is encountered where the requester's access still has unALLOWED bits | |||
in common with the "access_mask" of the ACE, the request is denied. | in common with the "access_mask" of the ACE, the request is denied. | |||
When the ACL is fully processed, if there are bits in the requester's | When the ACL is fully processed, if there are bits in the requester's | |||
skipping to change at page 100, line 6 | skipping to change at page 100, line 6 | |||
The attributes for entry "path" will not contain size or time_modify | The attributes for entry "path" will not contain size or time_modify | |||
because these attributes are not available within an absent file | because these attributes are not available within an absent file | |||
system. | system. | |||
7.9. The Attribute fs_locations | 7.9. The Attribute fs_locations | |||
The fs_locations attribute is structured in the following way: | The fs_locations attribute is structured in the following way: | |||
struct fs_location4 { | struct fs_location4 { | |||
utf8must server<>; | utf8val_must server<>; | |||
pathname4 rootpath; | pathname4 rootpath; | |||
}; | }; | |||
struct fs_locations4 { | struct fs_locations4 { | |||
pathname4 fs_root; | pathname4 fs_root; | |||
fs_location4 locations<>; | fs_location4 locations<>; | |||
}; | }; | |||
The fs_location4 data type is used to represent the location of a | The fs_location4 data type is used to represent the location of a | |||
file system by providing a server name and the path to the root of | file system by providing a server name and the path to the root of | |||
skipping to change at page 108, line 14 | skipping to change at page 108, line 14 | |||
and remain separate even if the same opaque arrays are used to | and remain separate even if the same opaque arrays are used to | |||
designate owners of each. The protocol distinguishes between open- | designate owners of each. The protocol distinguishes between open- | |||
owners (represented by open_owner4 structures) and lock-owners | owners (represented by open_owner4 structures) and lock-owners | |||
(represented by lock_owner4 structures). | (represented by lock_owner4 structures). | |||
Each open is associated with a specific open-owner while each byte- | Each open is associated with a specific open-owner while each byte- | |||
range lock is associated with a lock-owner and an open-owner, the | range lock is associated with a lock-owner and an open-owner, the | |||
latter being the open-owner associated with the open file under which | latter being the open-owner associated with the open file under which | |||
the LOCK operation was done. | the LOCK operation was done. | |||
Unlike the text in NFSv4.1 [31], this text treats "lock_owner" as | Unlike the text in NFSv4.1 [31], this text treats "lock-owner" as | |||
meaning both a open_owner4 and a lock_owner4. Also, a "lock" can | meaning both a open-owner and a lock-owner. Also, a "lock" can refer | |||
refer to both a byte-range and share lock. | to both a byte-range and share lock. | |||
Client identification is encapsulated in the following structure: | Client identification is encapsulated in the following structure: | |||
struct nfs_client_id4 { | struct nfs_client_id4 { | |||
verifier4 verifier; | verifier4 verifier; | |||
opaque id<NFS4_OPAQUE_LIMIT>; | opaque id<NFS4_OPAQUE_LIMIT>; | |||
}; | }; | |||
The first field, verifier is a client incarnation verifier that is | The first field, verifier is a client incarnation verifier that is | |||
used to detect client reboots. Only if the verifier is different | used to detect client reboots. Only if the verifier is different | |||
skipping to change at page 113, line 49 | skipping to change at page 113, line 49 | |||
and returning NFS4ERR_OLD_STATEID. This is because the client is not | and returning NFS4ERR_OLD_STATEID. This is because the client is not | |||
in a position to know the most up-to-date seqid and thus cannot | in a position to know the most up-to-date seqid and thus cannot | |||
verify it. Unless specially noted, the seqid value for a stateid | verify it. Unless specially noted, the seqid value for a stateid | |||
sent by the server to the client as part of a callback is required to | sent by the server to the client as part of a callback is required to | |||
be zero with NFS4ERR_BAD_STATEID returned if it is not. | be zero with NFS4ERR_BAD_STATEID returned if it is not. | |||
In making comparisons between seqids, both by the client in | In making comparisons between seqids, both by the client in | |||
determining the order of operations and by the server in determining | determining the order of operations and by the server in determining | |||
whether the NFS4ERR_OLD_STATEID is to be returned, the possibility of | whether the NFS4ERR_OLD_STATEID is to be returned, the possibility of | |||
the seqid being swapped around past the NFS4_UINT32_MAX value needs | the seqid being swapped around past the NFS4_UINT32_MAX value needs | |||
to be taken into account. When two seqid values are being compared, | to be taken into account. | |||
the total count of slots for all sessions associated with the current | ||||
client is used to do this. When one seqid value is less than this | ||||
total slot count and another seqid value is greater than | ||||
NFS4_UINT32_MAX minus the total slot count, the former is to be | ||||
treated as lower than the latter, despite the fact that it is | ||||
numerically greater. | ||||
9.1.3.3. Special Stateids | 9.1.3.3. Special Stateids | |||
Stateid values whose "other" field is either all zeros or all ones | Stateid values whose "other" field is either all zeros or all ones | |||
are reserved. They may not be assigned by the server but have | are reserved. They may not be assigned by the server but have | |||
special meanings defined by the protocol. The particular meaning | special meanings defined by the protocol. The particular meaning | |||
depends on whether the "other" field is all zeros or all ones and the | depends on whether the "other" field is all zeros or all ones and the | |||
specific value of the "seqid" field. | specific value of the "seqid" field. | |||
The following combinations of "other" and "seqid" are defined in | The following combinations of "other" and "seqid" are defined in | |||
skipping to change at page 118, line 48 | skipping to change at page 118, line 43 | |||
In the case of SETATTR operations, a stateid is present. In cases | In the case of SETATTR operations, a stateid is present. In cases | |||
other than those that set the file size, the client may send either a | other than those that set the file size, the client may send either a | |||
special stateid or, when a delegation is held for the file in | special stateid or, when a delegation is held for the file in | |||
question, a delegation stateid. While the server SHOULD validate the | question, a delegation stateid. While the server SHOULD validate the | |||
stateid and may use the stateid to optimize the determination as to | stateid and may use the stateid to optimize the determination as to | |||
whether a delegation is held, it SHOULD note the presence of a | whether a delegation is held, it SHOULD note the presence of a | |||
delegation even when a special stateid is sent, and MUST accept a | delegation even when a special stateid is sent, and MUST accept a | |||
valid delegation stateid when sent. | valid delegation stateid when sent. | |||
9.1.4. lock_owner | 9.1.4. lock-owner | |||
When requesting a lock, the client must present to the server the | When requesting a lock, the client must present to the server the | |||
client ID and an identifier for the owner of the requested lock. | client ID and an identifier for the owner of the requested lock. | |||
These two fields are referred to as the lock-owner and the definition | ||||
These two fields are referred to as the lock_owner and the definition | ||||
of those fields are: | of those fields are: | |||
o A client ID returned by the server as part of the client's use of | o A client ID returned by the server as part of the client's use of | |||
the SETCLIENTID operation. | the SETCLIENTID operation. | |||
o A variable length opaque array used to uniquely define the owner | o A variable length opaque array used to uniquely define the owner | |||
of a lock managed by the client. | of a lock managed by the client. | |||
This may be a thread id, process id, or other unique value. | This may be a thread id, process id, or other unique value. | |||
When the server grants the lock, it responds with a unique stateid. | When the server grants the lock, it responds with a unique stateid. | |||
The stateid is used as a shorthand reference to the lock_owner, since | The stateid is used as a shorthand reference to the lock-owner, since | |||
the server will be maintaining the correspondence between them. | the server will be maintaining the correspondence between them. | |||
9.1.5. Use of the Stateid and Locking | 9.1.5. Use of the Stateid and Locking | |||
All READ, WRITE and SETATTR operations contain a stateid. For the | All READ, WRITE and SETATTR operations contain a stateid. For the | |||
purposes of this section, SETATTR operations which change the size | purposes of this section, SETATTR operations which change the size | |||
attribute of a file are treated as if they are writing the area | attribute of a file are treated as if they are writing the area | |||
between the old and new size (i.e., the range truncated or added to | between the old and new size (i.e., the range truncated or added to | |||
the file by means of the SETATTR), even where SETATTR is not | the file by means of the SETATTR), even where SETATTR is not | |||
explicitly mentioned in the text. The stateid passed to one of these | explicitly mentioned in the text. The stateid passed to one of these | |||
operations must be one that represents an OPEN, a set of byte-range | operations must be one that represents an OPEN, a set of byte-range | |||
locks, or a delegation, or it may be a special stateid representing | locks, or a delegation, or it may be a special stateid representing | |||
anonymous access or the special bypass stateid. | anonymous access or the special bypass stateid. | |||
If the lock_owner performs a READ or WRITE in a situation in which it | If the lock-owner performs a READ or WRITE in a situation in which it | |||
has established a lock or share reservation on the server (any OPEN | has established a lock or share reservation on the server (any OPEN | |||
constitutes a share reservation) the stateid (previously returned by | constitutes a share reservation) the stateid (previously returned by | |||
the server) must be used to indicate what locks, including both byte- | the server) must be used to indicate what locks, including both byte- | |||
range locks and share reservations, are held by the lockowner. If no | range locks and share reservations, are held by the lockowner. If no | |||
state is established by the client, either byte-range lock or share | state is established by the client, either byte-range lock or share | |||
reservation, a stateid of all bits 0 is used. Regardless whether a | reservation, a stateid of all bits 0 is used. Regardless whether a | |||
stateid of all bits 0, or a stateid returned by the server is used, | stateid of all bits 0, or a stateid returned by the server is used, | |||
if there is a conflicting share reservation or mandatory byte-range | if there is a conflicting share reservation or mandatory byte-range | |||
lock held on the file, the server MUST refuse to service the READ or | lock held on the file, the server MUST refuse to service the READ or | |||
WRITE operation. | WRITE operation. | |||
skipping to change at page 121, line 42 | skipping to change at page 121, line 35 | |||
9.1.6. Sequencing of Lock Requests | 9.1.6. Sequencing of Lock Requests | |||
Locking is different than most NFS operations as it requires "at- | Locking is different than most NFS operations as it requires "at- | |||
most-one" semantics that are not provided by ONCRPC. ONCRPC over a | most-one" semantics that are not provided by ONCRPC. ONCRPC over a | |||
reliable transport is not sufficient because a sequence of locking | reliable transport is not sufficient because a sequence of locking | |||
requests may span multiple TCP connections. In the face of | requests may span multiple TCP connections. In the face of | |||
retransmission or reordering, lock or unlock requests must have a | retransmission or reordering, lock or unlock requests must have a | |||
well defined and consistent behavior. To accomplish this, each lock | well defined and consistent behavior. To accomplish this, each lock | |||
request contains a sequence number that is a consecutively increasing | request contains a sequence number that is a consecutively increasing | |||
integer. Different lock_owners have different sequences. The server | integer. Different lock-owners have different sequences. The server | |||
maintains the last sequence number (L) received and the response that | maintains the last sequence number (L) received and the response that | |||
was returned. The server is free to assign any value for the first | was returned. The server is free to assign any value for the first | |||
request issued for any given lock_owner. | request issued for any given lock-owner. | |||
Note that for requests that contain a sequence number, for each | Note that for requests that contain a sequence number, for each lock- | |||
lock_owner, there should be no more than one outstanding request. | owner, there should be no more than one outstanding request. | |||
If a request (r) with a previous sequence number (r < L) is received, | If a request (r) with a previous sequence number (r < L) is received, | |||
it is rejected with the return of error NFS4ERR_BAD_SEQID. Given a | it is rejected with the return of error NFS4ERR_BAD_SEQID. Given a | |||
properly-functioning client, the response to (r) must have been | properly-functioning client, the response to (r) must have been | |||
received before the last request (L) was sent. If a duplicate of | received before the last request (L) was sent. If a duplicate of | |||
last request (r == L) is received, the stored response is returned. | last request (r == L) is received, the stored response is returned. | |||
If a request beyond the next sequence (r == L + 2) is received, it is | If a request beyond the next sequence (r == L + 2) is received, it is | |||
rejected with the return of error NFS4ERR_BAD_SEQID. Sequence | rejected with the return of error NFS4ERR_BAD_SEQID. Sequence | |||
history is reinitialized whenever the SETCLIENTID/SETCLIENTID_CONFIRM | history is reinitialized whenever the SETCLIENTID/SETCLIENTID_CONFIRM | |||
sequence changes the client verifier. | sequence changes the client verifier. | |||
skipping to change at page 122, line 21 | skipping to change at page 122, line 15 | |||
Since the sequence number is represented with an unsigned 32-bit | Since the sequence number is represented with an unsigned 32-bit | |||
integer, the arithmetic involved with the sequence number is mod | integer, the arithmetic involved with the sequence number is mod | |||
2^32. For an example of modulo arithmetic involving sequence numbers | 2^32. For an example of modulo arithmetic involving sequence numbers | |||
see [33]. | see [33]. | |||
It is critical the server maintain the last response sent to the | It is critical the server maintain the last response sent to the | |||
client to provide a more reliable cache of duplicate non-idempotent | client to provide a more reliable cache of duplicate non-idempotent | |||
requests than that of the traditional cache described in [34]. The | requests than that of the traditional cache described in [34]. The | |||
traditional duplicate request cache uses a least recently used | traditional duplicate request cache uses a least recently used | |||
algorithm for removing unneeded requests. However, the last lock | algorithm for removing unneeded requests. However, the last lock | |||
request and response on a given lock_owner must be cached as long as | request and response on a given lock-owner must be cached as long as | |||
the lock state exists on the server. | the lock state exists on the server. | |||
The client MUST monotonically increment the sequence number for the | The client MUST monotonically increment the sequence number for the | |||
CLOSE, LOCK, LOCKU, OPEN, OPEN_CONFIRM, and OPEN_DOWNGRADE | CLOSE, LOCK, LOCKU, OPEN, OPEN_CONFIRM, and OPEN_DOWNGRADE | |||
operations. This is true even in the event that the previous | operations. This is true even in the event that the previous | |||
operation that used the sequence number received an error. The only | operation that used the sequence number received an error. The only | |||
exception to this rule is if the previous operation received one of | exception to this rule is if the previous operation received one of | |||
the following errors: NFS4ERR_STALE_CLIENTID, NFS4ERR_STALE_STATEID, | the following errors: NFS4ERR_STALE_CLIENTID, NFS4ERR_STALE_STATEID, | |||
NFS4ERR_BAD_STATEID, NFS4ERR_BAD_SEQID, NFS4ERR_BADXDR, | NFS4ERR_BAD_STATEID, NFS4ERR_BAD_SEQID, NFS4ERR_BADXDR, | |||
NFS4ERR_RESOURCE, NFS4ERR_NOFILEHANDLE, or NFS4ERR_MOVED. | NFS4ERR_RESOURCE, NFS4ERR_NOFILEHANDLE, or NFS4ERR_MOVED. | |||
9.1.7. Recovery from Replayed Requests | 9.1.7. Recovery from Replayed Requests | |||
As described above, the sequence number is per lock_owner. As long | As described above, the sequence number is per lock-owner. As long | |||
as the server maintains the last sequence number received and follows | as the server maintains the last sequence number received and follows | |||
the methods described above, there are no risks of a Byzantine router | the methods described above, there are no risks of a Byzantine router | |||
re-sending old requests. The server need only maintain the | re-sending old requests. The server need only maintain the (lock- | |||
(lock_owner, sequence number) state as long as there are open files | owner, sequence number) state as long as there are open files or | |||
or closed files with locks outstanding. | closed files with locks outstanding. | |||
LOCK, LOCKU, OPEN, OPEN_DOWNGRADE, and CLOSE each contain a sequence | LOCK, LOCKU, OPEN, OPEN_DOWNGRADE, and CLOSE each contain a sequence | |||
number and therefore the risk of the replay of these operations | number and therefore the risk of the replay of these operations | |||
resulting in undesired effects is non-existent while the server | resulting in undesired effects is non-existent while the server | |||
maintains the lock_owner state. | maintains the lock-owner state. | |||
9.1.8. Releasing lock_owner State | 9.1.8. Releasing lock-owner State | |||
When a particular lock_owner no longer holds open or file locking | When a particular lock-owner no longer holds open or file locking | |||
state at the server, the server may choose to release the sequence | state at the server, the server may choose to release the sequence | |||
number state associated with the lock_owner. The server may make | number state associated with the lock-owner. The server may make | |||
this choice based on lease expiration, for the reclamation of server | this choice based on lease expiration, for the reclamation of server | |||
memory, or other implementation specific details. In any event, the | memory, or other implementation specific details. In any event, the | |||
server is able to do this safely only when the lock_owner no longer | server is able to do this safely only when the lock-owner no longer | |||
is being utilized by the client. The server may choose to hold the | is being utilized by the client. The server may choose to hold the | |||
lock_owner state in the event that retransmitted requests are | lock-owner state in the event that retransmitted requests are | |||
received. However, the period to hold this state is implementation | received. However, the period to hold this state is implementation | |||
specific. | specific. | |||
In the case that a LOCK, LOCKU, OPEN_DOWNGRADE, or CLOSE is | In the case that a LOCK, LOCKU, OPEN_DOWNGRADE, or CLOSE is | |||
retransmitted after the server has previously released the lock_owner | retransmitted after the server has previously released the lock-owner | |||
state, the server will find that the lock_owner has no files open and | state, the server will find that the lock-owner has no files open and | |||
an error will be returned to the client. If the lock_owner does have | an error will be returned to the client. If the lock-owner does have | |||
a file open, the stateid will not match and again an error is | a file open, the stateid will not match and again an error is | |||
returned to the client. | returned to the client. | |||
9.1.9. Use of Open Confirmation | 9.1.9. Use of Open Confirmation | |||
In the case that an OPEN is retransmitted and the lock_owner is being | In the case that an OPEN is retransmitted and the lock-owner is being | |||
used for the first time or the lock_owner state has been previously | used for the first time or the lock-owner state has been previously | |||
released by the server, the use of the OPEN_CONFIRM operation will | released by the server, the use of the OPEN_CONFIRM operation will | |||
prevent incorrect behavior. When the server observes the use of the | prevent incorrect behavior. When the server observes the use of the | |||
lock_owner for the first time, it will direct the client to perform | lock-owner for the first time, it will direct the client to perform | |||
the OPEN_CONFIRM for the corresponding OPEN. This sequence | the OPEN_CONFIRM for the corresponding OPEN. This sequence | |||
establishes the use of a lock_owner and associated sequence number. | establishes the use of a lock-owner and associated sequence number. | |||
Since the OPEN_CONFIRM sequence connects a new open_owner on the | Since the OPEN_CONFIRM sequence connects a new open-owner on the | |||
server with an existing open_owner on a client, the sequence number | server with an existing open-owner on a client, the sequence number | |||
may have any value. The OPEN_CONFIRM step assures the server that | may have any value. The OPEN_CONFIRM step assures the server that | |||
the value received is the correct one. (see Section 15.20 for further | the value received is the correct one. (see Section 15.20 for further | |||
details.) | details.) | |||
There are a number of situations in which the requirement to confirm | There are a number of situations in which the requirement to confirm | |||
an OPEN would pose difficulties for the client and server, in that | an OPEN would pose difficulties for the client and server, in that | |||
they would be prevented from acting in a timely fashion on | they would be prevented from acting in a timely fashion on | |||
information received, because that information would be provisional, | information received, because that information would be provisional, | |||
subject to deletion upon non-confirmation. Fortunately, these are | subject to deletion upon non-confirmation. Fortunately, these are | |||
situations in which the server can avoid the need for confirmation | situations in which the server can avoid the need for confirmation | |||
skipping to change at page 136, line 25 | skipping to change at page 136, line 14 | |||
9.7. Recovery from a Lock Request Timeout or Abort | 9.7. Recovery from a Lock Request Timeout or Abort | |||
In the event a lock request times out, a client may decide to not | In the event a lock request times out, a client may decide to not | |||
retry the request. The client may also abort the request when the | retry the request. The client may also abort the request when the | |||
process for which it was issued is terminated (e.g., in UNIX due to a | process for which it was issued is terminated (e.g., in UNIX due to a | |||
signal). It is possible though that the server received the request | signal). It is possible though that the server received the request | |||
and acted upon it. This would change the state on the server without | and acted upon it. This would change the state on the server without | |||
the client being aware of the change. It is paramount that the | the client being aware of the change. It is paramount that the | |||
client re-synchronize state with server before it attempts any other | client re-synchronize state with server before it attempts any other | |||
operation that takes a seqid and/or a stateid with the same | operation that takes a seqid and/or a stateid with the same lock- | |||
lock_owner. This is straightforward to do without a special re- | owner. This is straightforward to do without a special re- | |||
synchronize operation. | synchronize operation. | |||
Since the server maintains the last lock request and response | Since the server maintains the last lock request and response | |||
received on the lock_owner, for each lock_owner, the client should | received on the lock-owner, for each lock-owner, the client should | |||
cache the last lock request it sent such that the lock request did | cache the last lock request it sent such that the lock request did | |||
not receive a response. From this, the next time the client does a | not receive a response. From this, the next time the client does a | |||
lock operation for the lock_owner, it can send the cached request, if | lock operation for the lock-owner, it can send the cached request, if | |||
there is one, and if the request was one that established state | there is one, and if the request was one that established state | |||
(e.g., a LOCK or OPEN operation), the server will return the cached | (e.g., a LOCK or OPEN operation), the server will return the cached | |||
result or if never saw the request, perform it. The client can | result or if never saw the request, perform it. The client can | |||
follow up with a request to remove the state (e.g., a LOCKU or CLOSE | follow up with a request to remove the state (e.g., a LOCKU or CLOSE | |||
operation). With this approach, the sequencing and stateid | operation). With this approach, the sequencing and stateid | |||
information on the client and server for the given lock_owner will | information on the client and server for the given lock-owner will | |||
re-synchronize and in turn the lock state will re-synchronize. | re-synchronize and in turn the lock state will re-synchronize. | |||
9.8. Server Revocation of Locks | 9.8. Server Revocation of Locks | |||
At any point, the server can revoke locks held by a client and the | At any point, the server can revoke locks held by a client and the | |||
client must be prepared for this event. When the client detects that | client must be prepared for this event. When the client detects that | |||
its locks have been or may have been revoked, the client is | its locks have been or may have been revoked, the client is | |||
responsible for validating the state information between itself and | responsible for validating the state information between itself and | |||
the server. Validating locking state for the client means that it | the server. Validating locking state for the client means that it | |||
must verify or reclaim state for each lock currently held. | must verify or reclaim state for each lock currently held. | |||
skipping to change at page 137, line 27 | skipping to change at page 137, line 16 | |||
client should bound the time that the corresponding renewal could | client should bound the time that the corresponding renewal could | |||
have occurred on the server and thus determine if it is possible that | have occurred on the server and thus determine if it is possible that | |||
a lease period expiration could have occurred. | a lease period expiration could have occurred. | |||
The third lock revocation event can occur as a result of | The third lock revocation event can occur as a result of | |||
administrative intervention within the lease period. While this is | administrative intervention within the lease period. While this is | |||
considered a rare event, it is possible that the server's | considered a rare event, it is possible that the server's | |||
administrator has decided to release or revoke a particular lock held | administrator has decided to release or revoke a particular lock held | |||
by the client. As a result of revocation, the client will receive an | by the client. As a result of revocation, the client will receive an | |||
error of NFS4ERR_ADMIN_REVOKED. In this instance the client may | error of NFS4ERR_ADMIN_REVOKED. In this instance the client may | |||
assume that only the lock_owner's locks have been lost. The client | assume that only the lock-owner's locks have been lost. The client | |||
notifies the lock holder appropriately. The client may not assume | notifies the lock holder appropriately. The client may not assume | |||
the lease period has been renewed as a result of a failed operation. | the lease period has been renewed as a result of a failed operation. | |||
When the client determines the lease period may have expired, the | When the client determines the lease period may have expired, the | |||
client must mark all locks held for the associated lease as | client must mark all locks held for the associated lease as | |||
"unvalidated". This means the client has been unable to re-establish | "unvalidated". This means the client has been unable to re-establish | |||
or confirm the appropriate lock state with the server. As described | or confirm the appropriate lock state with the server. As described | |||
in Section 9.6, there are scenarios in which the server may grant | in Section 9.6, there are scenarios in which the server may grant | |||
conflicting locks after the lease period has expired for a client. | conflicting locks after the lease period has expired for a client. | |||
When it is possible that the lease period has expired, the client | When it is possible that the lease period has expired, the client | |||
skipping to change at page 138, line 25 | skipping to change at page 138, line 12 | |||
Pseudo-code definition of the semantics: | Pseudo-code definition of the semantics: | |||
if (request.access == 0) | if (request.access == 0) | |||
return (NFS4ERR_INVAL) | return (NFS4ERR_INVAL) | |||
else if ((request.access & file_state.deny)) || | else if ((request.access & file_state.deny)) || | |||
(request.deny & file_state.access)) | (request.deny & file_state.access)) | |||
return (NFS4ERR_DENIED) | return (NFS4ERR_DENIED) | |||
This checking of share reservations on OPEN is done with no exception | This checking of share reservations on OPEN is done with no exception | |||
for an existing OPEN for the same open_owner. | for an existing OPEN for the same open-owner. | |||
The constants used for the OPEN and OPEN_DOWNGRADE operations for the | The constants used for the OPEN and OPEN_DOWNGRADE operations for the | |||
access and deny fields are as follows: | access and deny fields are as follows: | |||
const OPEN4_SHARE_ACCESS_READ = 0x00000001; | const OPEN4_SHARE_ACCESS_READ = 0x00000001; | |||
const OPEN4_SHARE_ACCESS_WRITE = 0x00000002; | const OPEN4_SHARE_ACCESS_WRITE = 0x00000002; | |||
const OPEN4_SHARE_ACCESS_BOTH = 0x00000003; | const OPEN4_SHARE_ACCESS_BOTH = 0x00000003; | |||
const OPEN4_SHARE_DENY_NONE = 0x00000000; | const OPEN4_SHARE_DENY_NONE = 0x00000000; | |||
const OPEN4_SHARE_DENY_READ = 0x00000001; | const OPEN4_SHARE_DENY_READ = 0x00000001; | |||
skipping to change at page 139, line 5 | skipping to change at page 138, line 41 | |||
to use a stateid of all 0's or all 1's, it must still obtain the | to use a stateid of all 0's or all 1's, it must still obtain the | |||
filehandle for the regular file with the OPEN operation so the | filehandle for the regular file with the OPEN operation so the | |||
appropriate share semantics can be applied. Clients that do not have | appropriate share semantics can be applied. Clients that do not have | |||
a deny mode built into their programming interfaces for opening a | a deny mode built into their programming interfaces for opening a | |||
file should request a deny mode of OPEN4_SHARE_DENY_NONE. | file should request a deny mode of OPEN4_SHARE_DENY_NONE. | |||
The OPEN operation with the CREATE flag, also subsumes the CREATE | The OPEN operation with the CREATE flag, also subsumes the CREATE | |||
operation for regular files as used in previous versions of the NFS | operation for regular files as used in previous versions of the NFS | |||
protocol. This allows a create with a share to be done atomically. | protocol. This allows a create with a share to be done atomically. | |||
The CLOSE operation removes all share reservations held by the | The CLOSE operation removes all share reservations held by the lock- | |||
lock_owner on that file. If byte-range locks are held, the client | owner on that file. If byte-range locks are held, the client SHOULD | |||
SHOULD release all locks before issuing a CLOSE. The server MAY free | release all locks before issuing a CLOSE. The server MAY free all | |||
all outstanding locks on CLOSE but some servers may not support the | outstanding locks on CLOSE but some servers may not support the CLOSE | |||
CLOSE of a file that still has byte-range locks held. The server | of a file that still has byte-range locks held. The server MUST | |||
MUST return failure, NFS4ERR_LOCKS_HELD, if any locks would exist | return failure, NFS4ERR_LOCKS_HELD, if any locks would exist after | |||
after the CLOSE. | the CLOSE. | |||
The LOOKUP operation will return a filehandle without establishing | The LOOKUP operation will return a filehandle without establishing | |||
any lock state on the server. Without a valid stateid, the server | any lock state on the server. Without a valid stateid, the server | |||
will assume the client has the least access. For example, if one | will assume the client has the least access. For example, if one | |||
client opened a file with OPEN4_SHARE_DENY_BOTH and another client | client opened a file with OPEN4_SHARE_DENY_BOTH and another client | |||
accesses the file via a filehandle obtained through LOOKUP, the | accesses the file via a filehandle obtained through LOOKUP, the | |||
second client could only read the file using the special read bypass | second client could only read the file using the special read bypass | |||
stateid. The second client could not WRITE the file at all because | stateid. The second client could not WRITE the file at all because | |||
it would not have a valid stateid from OPEN and the special anonymous | it would not have a valid stateid from OPEN and the special anonymous | |||
stateid would not be allowed access. | stateid would not be allowed access. | |||
skipping to change at page 146, line 37 | skipping to change at page 146, line 29 | |||
responsibilities when another client engages in sharing of a | responsibilities when another client engages in sharing of a | |||
delegated file. | delegated file. | |||
A delegation is passed from the server to the client, specifying the | A delegation is passed from the server to the client, specifying the | |||
object of the delegation and the type of delegation. There are | object of the delegation and the type of delegation. There are | |||
different types of delegations but each type contains a stateid to be | different types of delegations but each type contains a stateid to be | |||
used to represent the delegation when performing operations that | used to represent the delegation when performing operations that | |||
depend on the delegation. This stateid is similar to those | depend on the delegation. This stateid is similar to those | |||
associated with locks and share reservations but differs in that the | associated with locks and share reservations but differs in that the | |||
stateid for a delegation is associated with a client ID and may be | stateid for a delegation is associated with a client ID and may be | |||
used on behalf of all the open_owners for the given client. A | used on behalf of all the open-owners for the given client. A | |||
delegation is made to the client as a whole and not to any specific | delegation is made to the client as a whole and not to any specific | |||
process or thread of control within it. | process or thread of control within it. | |||
Because callback RPCs may not work in all environments (due to | Because callback RPCs may not work in all environments (due to | |||
firewalls, for example), correct protocol operation does not depend | firewalls, for example), correct protocol operation does not depend | |||
on them. Preliminary testing of callback functionality by means of a | on them. Preliminary testing of callback functionality by means of a | |||
CB_NULL procedure determines whether callbacks can be supported. The | CB_NULL procedure determines whether callbacks can be supported. The | |||
CB_NULL procedure checks the continuity of the callback path. A | CB_NULL procedure checks the continuity of the callback path. A | |||
server makes a preliminary assessment of callback availability to a | server makes a preliminary assessment of callback availability to a | |||
given client and avoids delegating responsibilities until it has | given client and avoids delegating responsibilities until it has | |||
skipping to change at page 155, line 48 | skipping to change at page 155, line 38 | |||
o space limitation information to control flushing of data on close | o space limitation information to control flushing of data on close | |||
(OPEN_DELEGATE_WRITE delegation only, see Section 10.4.1) | (OPEN_DELEGATE_WRITE delegation only, see Section 10.4.1) | |||
o an nfsace4 specifying read and write permissions | o an nfsace4 specifying read and write permissions | |||
o a stateid to represent the delegation for READ and WRITE | o a stateid to represent the delegation for READ and WRITE | |||
The delegation stateid is separate and distinct from the stateid for | The delegation stateid is separate and distinct from the stateid for | |||
the OPEN proper. The standard stateid, unlike the delegation | the OPEN proper. The standard stateid, unlike the delegation | |||
stateid, is associated with a particular lock_owner and will continue | stateid, is associated with a particular lock-owner and will continue | |||
to be valid after the delegation is recalled and the file remains | to be valid after the delegation is recalled and the file remains | |||
open. | open. | |||
When a request internal to the client is made to open a file and open | When a request internal to the client is made to open a file and open | |||
delegation is in effect, it will be accepted or rejected solely on | delegation is in effect, it will be accepted or rejected solely on | |||
the basis of the following conditions. Any requirement for other | the basis of the following conditions. Any requirement for other | |||
checks to be made by the delegate should result in open delegation | checks to be made by the delegate should result in open delegation | |||
being denied so that the checks can be made by the server itself. | being denied so that the checks can be made by the server itself. | |||
o The access and deny bits for the request and the file as described | o The access and deny bits for the request and the file as described | |||
skipping to change at page 201, line 8 | skipping to change at page 201, line 8 | |||
13.1.1.5. NFS4ERR_NOTSUPP (Error Code 10004) | 13.1.1.5. NFS4ERR_NOTSUPP (Error Code 10004) | |||
Operation not supported, either because the operation is an OPTIONAL | Operation not supported, either because the operation is an OPTIONAL | |||
one and is not supported by this server or because the operation MUST | one and is not supported by this server or because the operation MUST | |||
NOT be implemented in the current minor version. | NOT be implemented in the current minor version. | |||
13.1.1.6. NFS4ERR_SERVERFAULT (Error Code 10006) | 13.1.1.6. NFS4ERR_SERVERFAULT (Error Code 10006) | |||
An error occurred on the server which does not map to any of the | An error occurred on the server which does not map to any of the | |||
specific legal NFSv4.1 protocol error values. The client should | specific legal NFSv4 protocol error values. The client should | |||
translate this into an appropriate error. UNIX clients may choose to | translate this into an appropriate error. UNIX clients may choose to | |||
translate this to EIO. | translate this to EIO. | |||
13.1.1.7. NFS4ERR_TOOSMALL (Error Code 10005) | 13.1.1.7. NFS4ERR_TOOSMALL (Error Code 10005) | |||
Used where an operation returns a variable amount of data, with a | Used where an operation returns a variable amount of data, with a | |||
limit specified by the client. Where the data returned cannot be fit | limit specified by the client. Where the data returned cannot be fit | |||
within the limit specified by the client, this error results. | within the limit specified by the client, this error results. | |||
13.1.2. Filehandle Errors | 13.1.2. Filehandle Errors | |||
skipping to change at page 206, line 11 | skipping to change at page 206, line 11 | |||
A stateid with a non-zero seqid value does match the current seqid | A stateid with a non-zero seqid value does match the current seqid | |||
for the state designated by the user. | for the state designated by the user. | |||
13.1.5.6. NFS4ERR_STALE_STATEID (Error Code 10023) | 13.1.5.6. NFS4ERR_STALE_STATEID (Error Code 10023) | |||
A stateid generated by an earlier server instance was used. | A stateid generated by an earlier server instance was used. | |||
13.1.6. Security Errors | 13.1.6. Security Errors | |||
These are the various permission-related errors in NFSv4.1. | These are the various permission-related errors in NFSv4. | |||
13.1.6.1. NFS4ERR_ACCESS (Error Code 13) | 13.1.6.1. NFS4ERR_ACCESS (Error Code 13) | |||
Indicates permission denied. The caller does not have the correct | Indicates permission denied. The caller does not have the correct | |||
permission to perform the requested operation. Contrast this with | permission to perform the requested operation. Contrast this with | |||
NFS4ERR_PERM (Section 13.1.6.2), which restricts itself to owner or | NFS4ERR_PERM (Section 13.1.6.2), which restricts itself to owner or | |||
privileged user permission failures. | privileged user permission failures. | |||
13.1.6.2. NFS4ERR_PERM (Error Code 1) | 13.1.6.2. NFS4ERR_PERM (Error Code 1) | |||
skipping to change at page 234, line 11 | skipping to change at page 234, line 11 | |||
CLOSE but some servers may not support the CLOSE of a file that still | CLOSE but some servers may not support the CLOSE of a file that still | |||
has byte-range locks held. The server MUST return failure if any | has byte-range locks held. The server MUST return failure if any | |||
locks would exist after the CLOSE. | locks would exist after the CLOSE. | |||
On success, the current filehandle retains its value. | On success, the current filehandle retains its value. | |||
15.4.5. IMPLEMENTATION | 15.4.5. IMPLEMENTATION | |||
Even though CLOSE returns a stateid, this stateid is not useful to | Even though CLOSE returns a stateid, this stateid is not useful to | |||
the client and should be treated as deprecated. CLOSE "shuts down" | the client and should be treated as deprecated. CLOSE "shuts down" | |||
the state associated with all OPENs for the file by a single | the state associated with all OPENs for the file by a single open- | |||
open_owner. As noted above, CLOSE will either release all file | owner. As noted above, CLOSE will either release all file locking | |||
locking state or return an error. Therefore, the stateid returned by | state or return an error. Therefore, the stateid returned by CLOSE | |||
CLOSE is not useful for operations that follow. | is not useful for operations that follow. | |||
15.5. Operation 5: COMMIT - Commit Cached Data | 15.5. Operation 5: COMMIT - Commit Cached Data | |||
15.5.1. SYNOPSIS | 15.5.1. SYNOPSIS | |||
(cfh), offset, count -> verifier | (cfh), offset, count -> verifier | |||
15.5.2. ARGUMENT | 15.5.2. ARGUMENT | |||
struct COMMIT4args { | struct COMMIT4args { | |||
skipping to change at page 247, line 32 | skipping to change at page 247, line 32 | |||
When the client makes a lock request that corresponds to a range that | When the client makes a lock request that corresponds to a range that | |||
the lockowner has locked already (with the same or different lock | the lockowner has locked already (with the same or different lock | |||
type), or to a sub-region of such a range, or to a region which | type), or to a sub-region of such a range, or to a region which | |||
includes multiple locks already granted to that lockowner, in whole | includes multiple locks already granted to that lockowner, in whole | |||
or in part, and the server does not support such locking operations | or in part, and the server does not support such locking operations | |||
(i.e., does not support POSIX locking semantics), the server will | (i.e., does not support POSIX locking semantics), the server will | |||
return the error NFS4ERR_LOCK_RANGE. In that case, the client may | return the error NFS4ERR_LOCK_RANGE. In that case, the client may | |||
return an error, or it may emulate the required operations, using | return an error, or it may emulate the required operations, using | |||
only LOCK for ranges that do not include any bytes already locked by | only LOCK for ranges that do not include any bytes already locked by | |||
that lock_owner and LOCKU of locks held by that lock_owner | that lock-owner and LOCKU of locks held by that lock-owner | |||
(specifying an exactly-matching range and type). Similarly, when the | (specifying an exactly-matching range and type). Similarly, when the | |||
client makes a lock request that amounts to upgrading (changing from | client makes a lock request that amounts to upgrading (changing from | |||
a read lock to a write lock) or downgrading (changing from write lock | a read lock to a write lock) or downgrading (changing from write lock | |||
to a read lock) an existing record lock, and the server does not | to a read lock) an existing record lock, and the server does not | |||
support such a lock, the server will return NFS4ERR_LOCK_NOTSUPP. | support such a lock, the server will return NFS4ERR_LOCK_NOTSUPP. | |||
Such operations may not perfectly reflect the required semantics in | Such operations may not perfectly reflect the required semantics in | |||
the face of conflicting lock requests from other clients. | the face of conflicting lock requests from other clients. | |||
When a client holds an OPEN_DELEGATE_WRITE delegation, the client | When a client holds an OPEN_DELEGATE_WRITE delegation, the client | |||
holding that delegation is assured that there are no opens by other | holding that delegation is assured that there are no opens by other | |||
skipping to change at page 262, line 5 | skipping to change at page 262, line 5 | |||
OPEN_CONFIRM operation before using the open file. | OPEN_CONFIRM operation before using the open file. | |||
OPEN4_RESULT_LOCKTYPE_POSIX indicates the server's file locking | OPEN4_RESULT_LOCKTYPE_POSIX indicates the server's file locking | |||
behavior supports the complete set of Posix locking techniques [35]. | behavior supports the complete set of Posix locking techniques [35]. | |||
From this the client can choose to manage file locking state in a way | From this the client can choose to manage file locking state in a way | |||
to handle a mis-match of file locking management. | to handle a mis-match of file locking management. | |||
If the component is of zero length, NFS4ERR_INVAL will be returned. | If the component is of zero length, NFS4ERR_INVAL will be returned. | |||
The component is also subject to the normal UTF-8, character support, | The component is also subject to the normal UTF-8, character support, | |||
and name checks. See Section 12.3 for further discussion. | and name checks. See Section 12.3 for further discussion. | |||
When an OPEN is done and the specified open_owner already has the | When an OPEN is done and the specified open-owner already has the | |||
resulting filehandle open, the result is to "OR" together the new | resulting filehandle open, the result is to "OR" together the new | |||
share and deny status together with the existing status. In this | share and deny status together with the existing status. In this | |||
case, only a single CLOSE need be done, even though multiple OPENs | case, only a single CLOSE need be done, even though multiple OPENs | |||
were completed. When such an OPEN is done, checking of share | were completed. When such an OPEN is done, checking of share | |||
reservations for the new OPEN proceeds normally, with no exception | reservations for the new OPEN proceeds normally, with no exception | |||
for the existing OPEN held by the same owner. In this case, the | for the existing OPEN held by the same owner. In this case, the | |||
stateid returned as an "other" field that matches that of the | stateid returned as an "other" field that matches that of the | |||
previous open while the "seqid" field is incremented to reflect the | previous open while the "seqid" field is incremented to reflect the | |||
change status due to the new open. | change status due to the new open. | |||
skipping to change at page 266, line 35 | skipping to change at page 266, line 35 | |||
union OPEN_CONFIRM4res switch (nfsstat4 status) { | union OPEN_CONFIRM4res switch (nfsstat4 status) { | |||
case NFS4_OK: | case NFS4_OK: | |||
OPEN_CONFIRM4resok resok4; | OPEN_CONFIRM4resok resok4; | |||
default: | default: | |||
void; | void; | |||
}; | }; | |||
15.20.4. DESCRIPTION | 15.20.4. DESCRIPTION | |||
This operation is used to confirm the sequence id usage for the first | This operation is used to confirm the sequence id usage for the first | |||
time that a open_owner is used by a client. The stateid returned | time that a open-owner is used by a client. The stateid returned | |||
from the OPEN operation is used as the argument for this operation | from the OPEN operation is used as the argument for this operation | |||
along with the next sequence id for the open_owner. The sequence id | along with the next sequence id for the open-owner. The sequence id | |||
passed to the OPEN_CONFIRM must be 1 (one) greater than the seqid | passed to the OPEN_CONFIRM must be 1 (one) greater than the seqid | |||
passed to the OPEN operation. If the server receives an unexpected | passed to the OPEN operation. If the server receives an unexpected | |||
sequence id with respect to the original open, then the server | sequence id with respect to the original open, then the server | |||
assumes that the client will not confirm the original OPEN and all | assumes that the client will not confirm the original OPEN and all | |||
state associated with the original OPEN is released by the server. | state associated with the original OPEN is released by the server. | |||
On success, the current filehandle retains its value. | On success, the current filehandle retains its value. | |||
15.20.5. IMPLEMENTATION | 15.20.5. IMPLEMENTATION | |||
skipping to change at page 304, line 37 | skipping to change at page 304, line 37 | |||
}; | }; | |||
15.39.3. RESULT | 15.39.3. RESULT | |||
struct RELEASE_LOCKOWNER4res { | struct RELEASE_LOCKOWNER4res { | |||
nfsstat4 status; | nfsstat4 status; | |||
}; | }; | |||
15.39.4. DESCRIPTION | 15.39.4. DESCRIPTION | |||
This operation is used to notify the server that the lock_owner is no | This operation is used to notify the server that the lock-owner is no | |||
longer in use by the client. This allows the server to release | longer in use by the client. This allows the server to release | |||
cached state related to the specified lock_owner. If file locks, | cached state related to the specified lock-owner. If file locks, | |||
associated with the lock_owner, are held at the server, the error | associated with the lock-owner, are held at the server, the error | |||
NFS4ERR_LOCKS_HELD will be returned and no further action will be | NFS4ERR_LOCKS_HELD will be returned and no further action will be | |||
taken. | taken. | |||
15.39.5. IMPLEMENTATION | 15.39.5. IMPLEMENTATION | |||
The client may choose to use this operation to ease the amount of | The client may choose to use this operation to ease the amount of | |||
server state that is held. Depending on behavior of applications at | server state that is held. Depending on behavior of applications at | |||
the client, it may be important for the client to use this operation | the client, it may be important for the client to use this operation | |||
since the server has certain obligations with respect to holding a | since the server has certain obligations with respect to holding a | |||
reference to a lock_owner as long as the associated file is open. | reference to a lock-owner as long as the associated file is open. | |||
Therefore, if the client knows for certain that the lock_owner will | Therefore, if the client knows for certain that the lock-owner will | |||
no longer be used under the context of the associated open_owner4, it | no longer be used under the context of the associated open_owner4, it | |||
should use RELEASE_LOCKOWNER. | should use RELEASE_LOCKOWNER. | |||
15.40. Operation 10044: ILLEGAL - Illegal operation | 15.40. Operation 10044: ILLEGAL - Illegal operation | |||
15.40.1. SYNOPSIS | 15.40.1. SYNOPSIS | |||
<null> -> () | <null> -> () | |||
15.40.2. ARGUMENT | 15.40.2. ARGUMENT | |||
End of changes. 69 change blocks. | ||||
333 lines changed or deleted | 320 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/ |