From 4bfd864f10b68b71482b35c818559068ef8d5797 Mon Sep 17 00:00:00 2001 From: Thomas Voss Date: Wed, 27 Nov 2024 20:54:24 +0100 Subject: doc: Add RFC documents --- doc/rfc/rfc7530.txt | 18091 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 18091 insertions(+) create mode 100644 doc/rfc/rfc7530.txt (limited to 'doc/rfc/rfc7530.txt') diff --git a/doc/rfc/rfc7530.txt b/doc/rfc/rfc7530.txt new file mode 100644 index 0000000..6af9714 --- /dev/null +++ b/doc/rfc/rfc7530.txt @@ -0,0 +1,18091 @@ + + + + + + +Internet Engineering Task Force (IETF) T. Haynes, Ed. +Request for Comments: 7530 Primary Data +Obsoletes: 3530 D. Noveck, Ed. +Category: Standards Track Dell +ISSN: 2070-1721 March 2015 + + + Network File System (NFS) Version 4 Protocol + +Abstract + + The Network File System (NFS) version 4 protocol is a distributed + file system protocol that builds on the heritage of NFS protocol + version 2 (RFC 1094) and version 3 (RFC 1813). Unlike earlier + versions, the NFS version 4 protocol supports traditional file access + while integrating support for file locking and the MOUNT protocol. + In addition, support for strong security (and its negotiation), + COMPOUND operations, client caching, and internationalization has + been added. Of course, attention has been applied to making NFS + version 4 operate well in an Internet environment. + + This document, together with the companion External Data + Representation (XDR) description document, RFC 7531, obsoletes RFC + 3530 as the definition of the NFS version 4 protocol. + +Status of This Memo + + This is an Internet Standards Track document. + + This document is a product of the Internet Engineering Task Force + (IETF). It represents the consensus of the IETF community. It has + received public review and has been approved for publication by the + Internet Engineering Steering Group (IESG). Further information on + Internet Standards is available in Section 2 of RFC 5741. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + http://www.rfc-editor.org/info/rfc7530. + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 1] + +RFC 7530 NFSv4 March 2015 + + +Copyright Notice + + Copyright (c) 2015 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (http://trustee.ietf.org/license-info) in effect on the date of + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with respect + to this document. Code Components extracted from this document must + include Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. + + This document may contain material from IETF Documents or IETF + Contributions published or made publicly available before November + 10, 2008. The person(s) controlling the copyright in some of this + material may not have granted the IETF Trust the right to allow + modifications of such material outside the IETF Standards Process. + Without obtaining an adequate license from the person(s) controlling + the copyright in such materials, this document may not be modified + outside the IETF Standards Process, and derivative works of it may + not be created outside the IETF Standards Process, except to format + it for publication as an RFC or to translate it into languages other + than English. + +Table of Contents + + 1. Introduction ....................................................8 + 1.1. Requirements Language ......................................8 + 1.2. NFS Version 4 Goals ........................................8 + 1.3. Definitions in the Companion Document RFC 7531 Are + Authoritative ..............................................9 + 1.4. Overview of NFSv4 Features .................................9 + 1.4.1. RPC and Security ....................................9 + 1.4.2. Procedure and Operation Structure ..................10 + 1.4.3. File System Model ..................................10 + 1.4.4. OPEN and CLOSE .....................................12 + 1.4.5. File Locking .......................................12 + 1.4.6. Client Caching and Delegation ......................13 + 1.5. General Definitions .......................................14 + 1.6. Changes since RFC 3530 ....................................16 + 1.7. Changes between RFC 3010 and RFC 3530 .....................16 + 2. Protocol Data Types ............................................18 + 2.1. Basic Data Types ..........................................18 + 2.2. Structured Data Types .....................................21 + + + + +Haynes & Noveck Standards Track [Page 2] + +RFC 7530 NFSv4 March 2015 + + + 3. RPC and Security Flavor ........................................25 + 3.1. Ports and Transports ......................................25 + 3.1.1. Client Retransmission Behavior .....................26 + 3.2. Security Flavors ..........................................27 + 3.2.1. Security Mechanisms for NFSv4 ......................27 + 3.3. Security Negotiation ......................................28 + 3.3.1. SECINFO ............................................29 + 3.3.2. Security Error .....................................29 + 3.3.3. Callback RPC Authentication ........................29 + 4. Filehandles ....................................................30 + 4.1. Obtaining the First Filehandle ............................30 + 4.1.1. Root Filehandle ....................................31 + 4.1.2. Public Filehandle ..................................31 + 4.2. Filehandle Types ..........................................31 + 4.2.1. General Properties of a Filehandle .................32 + 4.2.2. Persistent Filehandle ..............................32 + 4.2.3. Volatile Filehandle ................................33 + 4.2.4. One Method of Constructing a Volatile Filehandle ...34 + 4.3. Client Recovery from Filehandle Expiration ................35 + 5. Attributes .....................................................35 + 5.1. REQUIRED Attributes .......................................37 + 5.2. RECOMMENDED Attributes ....................................37 + 5.3. Named Attributes ..........................................37 + 5.4. Classification of Attributes ..............................39 + 5.5. Set-Only and Get-Only Attributes ..........................40 + 5.6. REQUIRED Attributes - List and Definition References ......40 + 5.7. RECOMMENDED Attributes - List and Definition References ...41 + 5.8. Attribute Definitions .....................................42 + 5.8.1. Definitions of REQUIRED Attributes .................42 + 5.8.2. Definitions of Uncategorized RECOMMENDED + Attributes .........................................45 + 5.9. Interpreting owner and owner_group ........................51 + 5.10. Character Case Attributes ................................53 + 6. Access Control Attributes ......................................54 + 6.1. Goals .....................................................54 + 6.2. File Attributes Discussion ................................55 + 6.2.1. Attribute 12: acl ..................................55 + 6.2.2. Attribute 33: mode .................................70 + 6.3. Common Methods ............................................71 + 6.3.1. Interpreting an ACL ................................71 + 6.3.2. Computing a mode Attribute from an ACL .............72 + 6.4. Requirements ..............................................73 + 6.4.1. Setting the mode and/or ACL Attributes .............74 + 6.4.2. Retrieving the mode and/or ACL Attributes ..........75 + 6.4.3. Creating New Objects ...............................75 + + + + + + +Haynes & Noveck Standards Track [Page 3] + +RFC 7530 NFSv4 March 2015 + + + 7. NFS Server Namespace ...........................................77 + 7.1. Server Exports ............................................77 + 7.2. Browsing Exports ..........................................77 + 7.3. Server Pseudo-File System .................................78 + 7.4. Multiple Roots ............................................79 + 7.5. Filehandle Volatility .....................................79 + 7.6. Exported Root .............................................79 + 7.7. Mount Point Crossing ......................................79 + 7.8. Security Policy and Namespace Presentation ................80 + 8. Multi-Server Namespace .........................................81 + 8.1. Location Attributes .......................................81 + 8.2. File System Presence or Absence ...........................81 + 8.3. Getting Attributes for an Absent File System ..............83 + 8.3.1. GETATTR within an Absent File System ...............83 + 8.3.2. READDIR and Absent File Systems ....................84 + 8.4. Uses of Location Information ..............................84 + 8.4.1. File System Replication ............................85 + 8.4.2. File System Migration ..............................86 + 8.4.3. Referrals ..........................................86 + 8.5. Location Entries and Server Identity ......................87 + 8.6. Additional Client-Side Considerations .....................88 + 8.7. Effecting File System Referrals ...........................89 + 8.7.1. Referral Example (LOOKUP) ..........................89 + 8.7.2. Referral Example (READDIR) .........................93 + 8.8. The Attribute fs_locations ................................96 + 9. File Locking and Share Reservations ............................98 + 9.1. Opens and Byte-Range Locks ................................99 + 9.1.1. Client ID ..........................................99 + 9.1.2. Server Release of Client ID .......................102 + 9.1.3. Use of Seqids .....................................103 + 9.1.4. Stateid Definition ................................104 + 9.1.5. Lock-Owner ........................................110 + 9.1.6. Use of the Stateid and Locking ....................110 + 9.1.7. Sequencing of Lock Requests .......................113 + 9.1.8. Recovery from Replayed Requests ...................114 + 9.1.9. Interactions of Multiple Sequence Values ..........114 + 9.1.10. Releasing State-Owner State ......................115 + 9.1.11. Use of Open Confirmation .........................116 + 9.2. Lock Ranges ..............................................117 + 9.3. Upgrading and Downgrading Locks ..........................117 + 9.4. Blocking Locks ...........................................118 + 9.5. Lease Renewal ............................................119 + 9.6. Crash Recovery ...........................................120 + 9.6.1. Client Failure and Recovery .......................120 + 9.6.2. Server Failure and Recovery .......................120 + 9.6.3. Network Partitions and Recovery ...................122 + 9.7. Recovery from a Lock Request Timeout or Abort ............130 + 9.8. Server Revocation of Locks ...............................130 + + + +Haynes & Noveck Standards Track [Page 4] + +RFC 7530 NFSv4 March 2015 + + + 9.9. Share Reservations .......................................132 + 9.10. OPEN/CLOSE Operations ...................................132 + 9.10.1. Close and Retention of State Information .........133 + 9.11. Open Upgrade and Downgrade ..............................134 + 9.12. Short and Long Leases ...................................135 + 9.13. Clocks, Propagation Delay, and Calculating Lease + Expiration ..............................................135 + 9.14. Migration, Replication, and State .......................136 + 9.14.1. Migration and State ..............................136 + 9.14.2. Replication and State ............................137 + 9.14.3. Notification of Migrated Lease ...................137 + 9.14.4. Migration and the lease_time Attribute ...........138 + 10. Client-Side Caching ..........................................139 + 10.1. Performance Challenges for Client-Side Caching ..........139 + 10.2. Delegation and Callbacks ................................140 + 10.2.1. Delegation Recovery ..............................142 + 10.3. Data Caching ............................................147 + 10.3.1. Data Caching and OPENs ...........................147 + 10.3.2. Data Caching and File Locking ....................148 + 10.3.3. Data Caching and Mandatory File Locking ..........150 + 10.3.4. Data Caching and File Identity ...................150 + 10.4. Open Delegation .........................................151 + 10.4.1. Open Delegation and Data Caching .................154 + 10.4.2. Open Delegation and File Locks ...................155 + 10.4.3. Handling of CB_GETATTR ...........................155 + 10.4.4. Recall of Open Delegation ........................158 + 10.4.5. OPEN Delegation Race with CB_RECALL ..............160 + 10.4.6. Clients That Fail to Honor Delegation Recalls ....161 + 10.4.7. Delegation Revocation ............................162 + 10.5. Data Caching and Revocation .............................162 + 10.5.1. Revocation Recovery for Write Open Delegation ....163 + 10.6. Attribute Caching .......................................164 + 10.7. Data and Metadata Caching and Memory-Mapped Files .......166 + 10.8. Name Caching ............................................168 + 10.9. Directory Caching .......................................169 + 11. Minor Versioning .............................................170 + 12. Internationalization .........................................170 + 12.1. Introduction ............................................170 + 12.2. Limitations on Internationalization-Related + Processing in the NFSv4 Context .........................172 + 12.3. Summary of Server Behavior Types ........................173 + 12.4. String Encoding .........................................173 + 12.5. Normalization ...........................................174 + 12.6. Types with Processing Defined by Other Internet Areas ...175 + 12.7. Errors Related to UTF-8 .................................177 + 12.8. Servers That Accept File Component Names That + Are Not Valid UTF-8 Strings .............................177 + + + + +Haynes & Noveck Standards Track [Page 5] + +RFC 7530 NFSv4 March 2015 + + + 13. Error Values .................................................178 + 13.1. Error Definitions .......................................179 + 13.1.1. General Errors ...................................180 + 13.1.2. Filehandle Errors ................................181 + 13.1.3. Compound Structure Errors ........................183 + 13.1.4. File System Errors ...............................184 + 13.1.5. State Management Errors ..........................186 + 13.1.6. Security Errors ..................................187 + 13.1.7. Name Errors ......................................187 + 13.1.8. Locking Errors ...................................188 + 13.1.9. Reclaim Errors ...................................190 + 13.1.10. Client Management Errors ........................191 + 13.1.11. Attribute Handling Errors .......................191 + 13.1.12. Miscellaneous Errors ............................191 + 13.2. Operations and Their Valid Errors .......................192 + 13.3. Callback Operations and Their Valid Errors ..............200 + 13.4. Errors and the Operations That Use Them .................201 + 14. NFSv4 Requests ...............................................206 + 14.1. COMPOUND Procedure ......................................207 + 14.2. Evaluation of a COMPOUND Request ........................207 + 14.3. Synchronous Modifying Operations ........................208 + 14.4. Operation Values ........................................208 + 15. NFSv4 Procedures .............................................209 + 15.1. Procedure 0: NULL - No Operation ........................209 + 15.2. Procedure 1: COMPOUND - COMPOUND Operations .............210 + 16. NFSv4 Operations .............................................214 + 16.1. Operation 3: ACCESS - Check Access Rights ...............214 + 16.2. Operation 4: CLOSE - Close File .........................217 + 16.3. Operation 5: COMMIT - Commit Cached Data ................218 + 16.4. Operation 6: CREATE - Create a Non-regular File Object ..221 + 16.5. Operation 7: DELEGPURGE - Purge Delegations + Awaiting Recovery .......................................224 + 16.6. Operation 8: DELEGRETURN - Return Delegation ............226 + 16.7. Operation 9: GETATTR - Get Attributes ...................227 + 16.8. Operation 10: GETFH - Get Current Filehandle ............229 + 16.9. Operation 11: LINK - Create Link to a File ..............230 + 16.10. Operation 12: LOCK - Create Lock .......................232 + 16.11. Operation 13: LOCKT - Test for Lock ....................236 + 16.12. Operation 14: LOCKU - Unlock File ......................238 + 16.13. Operation 15: LOOKUP - Look Up Filename ................240 + 16.14. Operation 16: LOOKUPP - Look Up Parent Directory .......242 + 16.15. Operation 17: NVERIFY - Verify Difference in + Attributes .............................................243 + 16.16. Operation 18: OPEN - Open a Regular File ...............245 + + + + + + + +Haynes & Noveck Standards Track [Page 6] + +RFC 7530 NFSv4 March 2015 + + + 16.17. Operation 19: OPENATTR - Open Named Attribute + Directory ..............................................256 + 16.18. Operation 20: OPEN_CONFIRM - Confirm Open ..............257 + 16.19. Operation 21: OPEN_DOWNGRADE - Reduce Open File + Access .................................................260 + 16.20. Operation 22: PUTFH - Set Current Filehandle ...........262 + 16.21. Operation 23: PUTPUBFH - Set Public Filehandle .........263 + 16.22. Operation 24: PUTROOTFH - Set Root Filehandle ..........265 + 16.23. Operation 25: READ - Read from File ....................266 + 16.24. Operation 26: READDIR - Read Directory .................269 + 16.25. Operation 27: READLINK - Read Symbolic Link ............273 + 16.26. Operation 28: REMOVE - Remove File System Object .......274 + 16.27. Operation 29: RENAME - Rename Directory Entry ..........276 + 16.28. Operation 30: RENEW - Renew a Lease ....................278 + 16.29. Operation 31: RESTOREFH - Restore Saved Filehandle .....280 + 16.30. Operation 32: SAVEFH - Save Current Filehandle .........281 + 16.31. Operation 33: SECINFO - Obtain Available Security ......282 + 16.32. Operation 34: SETATTR - Set Attributes .................286 + 16.33. Operation 35: SETCLIENTID - Negotiate Client ID ........289 + 16.34. Operation 36: SETCLIENTID_CONFIRM - Confirm Client ID ..293 + 16.35. Operation 37: VERIFY - Verify Same Attributes ..........297 + 16.36. Operation 38: WRITE - Write to File ....................299 + 16.37. Operation 39: RELEASE_LOCKOWNER - Release + Lock-Owner State .......................................304 + 16.38. Operation 10044: ILLEGAL - Illegal Operation ...........305 + 17. NFSv4 Callback Procedures ....................................306 + 17.1. Procedure 0: CB_NULL - No Operation .....................306 + 17.2. Procedure 1: CB_COMPOUND - COMPOUND Operations ..........307 + 18. NFSv4 Callback Operations ....................................309 + 18.1. Operation 3: CB_GETATTR - Get Attributes ................309 + 18.2. Operation 4: CB_RECALL - Recall an Open Delegation ......310 + 18.3. Operation 10044: CB_ILLEGAL - Illegal Callback + Operation ...............................................311 + 19. Security Considerations ......................................312 + 20. IANA Considerations ..........................................314 + 20.1. Named Attribute Definitions .............................314 + 20.1.1. Initial Registry .................................315 + 20.1.2. Updating Registrations ...........................315 + 20.2. Updates to Existing IANA Registries .....................315 + 21. References ...................................................316 + 21.1. Normative References ....................................316 + 21.2. Informative References ..................................318 + Acknowledgments ..................................................322 + Authors' Addresses ...............................................323 + + + + + + + +Haynes & Noveck Standards Track [Page 7] + +RFC 7530 NFSv4 March 2015 + + +1. Introduction + +1.1. Requirements Language + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in RFC 2119 [RFC2119], + except where "REQUIRED" and "RECOMMENDED" are used as qualifiers to + distinguish classes of attributes as described in Sections 1.4.3.2 + and 5 of this document. + +1.2. NFS Version 4 Goals + + The Network File System version 4 (NFSv4) protocol is a further + revision of the NFS protocol defined already by versions 2 [RFC1094] + and 3 [RFC1813]. It retains the essential characteristics of + previous versions: design for easy recovery; independent of transport + protocols, operating systems, and file systems; simplicity; and good + performance. The NFSv4 revision has the following goals: + + o Improved access and good performance on the Internet. + + The protocol is designed to transit firewalls easily, perform well + where latency is high and bandwidth is low, and scale to very + large numbers of clients per server. + + o Strong security with negotiation built into the protocol. + + The protocol builds on the work of the Open Network Computing + (ONC) Remote Procedure Call (RPC) working group in supporting the + RPCSEC_GSS protocol (see both [RFC2203] and [RFC5403]). + Additionally, the NFSv4 protocol provides a mechanism to allow + clients and servers the ability to negotiate security and require + clients and servers to support a minimal set of security schemes. + + o Good cross-platform interoperability. + + The protocol features a file system model that provides a useful, + common set of features that does not unduly favor one file system + or operating system over another. + + o Designed for protocol extensions. + + The protocol is designed to accept standard extensions that do not + compromise backward compatibility. + + + + + + +Haynes & Noveck Standards Track [Page 8] + +RFC 7530 NFSv4 March 2015 + + + This document, together with the companion External Data + Representation (XDR) description document [RFC7531], obsoletes + [RFC3530] as the authoritative document describing NFSv4. It does + not introduce any over-the-wire protocol changes, in the sense that + previously valid requests remain valid. + +1.3. Definitions in the Companion Document RFC 7531 Are Authoritative + + The "Network File System (NFS) Version 4 External Data Representation + Standard (XDR) Description" [RFC7531] contains the definitions in XDR + description language of the constructs used by the protocol. Inside + this document, several of the constructs are reproduced for purposes + of explanation. The reader is warned of the possibility of errors in + the reproduced constructs outside of [RFC7531]. For any part of the + document that is inconsistent with [RFC7531], [RFC7531] is to be + considered authoritative. + +1.4. Overview of NFSv4 Features + + To provide a reasonable context for the reader, the major features of + the NFSv4 protocol will be reviewed in brief. This is done to + provide an appropriate context for both the reader who is familiar + with the previous versions of the NFS protocol and the reader who is + new to the NFS protocols. For the reader new to the NFS protocols, + some fundamental knowledge is still expected. The reader should be + familiar with the XDR and RPC protocols as described in [RFC4506] and + [RFC5531]. A basic knowledge of file systems and distributed file + systems is expected as well. + +1.4.1. RPC and Security + + As with previous versions of NFS, the XDR and RPC mechanisms used for + the NFSv4 protocol are those defined in [RFC4506] and [RFC5531]. To + meet end-to-end security requirements, the RPCSEC_GSS framework (both + version 1 in [RFC2203] and version 2 in [RFC5403]) will be used to + extend the basic RPC security. With the use of RPCSEC_GSS, various + mechanisms can be provided to offer authentication, integrity, and + privacy to the NFSv4 protocol. Kerberos V5 will be used as described + in [RFC4121] to provide one security framework. With the use of + RPCSEC_GSS, other mechanisms may also be specified and used for NFSv4 + security. + + To enable in-band security negotiation, the NFSv4 protocol has added + a new operation that provides the client with a method of querying + the server about its policies regarding which security mechanisms + must be used for access to the server's file system resources. With + this, the client can securely match the security mechanism that meets + the policies specified at both the client and server. + + + +Haynes & Noveck Standards Track [Page 9] + +RFC 7530 NFSv4 March 2015 + + +1.4.2. Procedure and Operation Structure + + A significant departure from the previous versions of the NFS + protocol is the introduction of the COMPOUND procedure. For the + NFSv4 protocol, there are two RPC procedures: NULL and COMPOUND. The + COMPOUND procedure is defined in terms of operations, and these + operations correspond more closely to the traditional NFS procedures. + + With the use of the COMPOUND procedure, the client is able to build + simple or complex requests. These COMPOUND requests allow for a + reduction in the number of RPCs needed for logical file system + operations. For example, without previous contact with a server a + client will be able to read data from a file in one request by + combining LOOKUP, OPEN, and READ operations in a single COMPOUND RPC. + With previous versions of the NFS protocol, this type of single + request was not possible. + + The model used for COMPOUND is very simple. There is no logical OR + or ANDing of operations. The operations combined within a COMPOUND + request are evaluated in order by the server. Once an operation + returns a failing result, the evaluation ends and the results of all + evaluated operations are returned to the client. + + The NFSv4 protocol continues to have the client refer to a file or + directory at the server by a "filehandle". The COMPOUND procedure + has a method of passing a filehandle from one operation to another + within the sequence of operations. There is a concept of a current + filehandle and a saved filehandle. Most operations use the current + filehandle as the file system object to operate upon. The saved + filehandle is used as temporary filehandle storage within a COMPOUND + procedure as well as an additional operand for certain operations. + +1.4.3. File System Model + + The general file system model used for the NFSv4 protocol is the same + as previous versions. The server file system is hierarchical, with + the regular files contained within being treated as opaque byte + streams. In a slight departure, file and directory names are encoded + with UTF-8 to deal with the basics of internationalization. + + The NFSv4 protocol does not require a separate protocol to provide + for the initial mapping between pathname and filehandle. Instead of + using the older MOUNT protocol for this mapping, the server provides + a root filehandle that represents the logical root or top of the file + system tree provided by the server. The server provides multiple + file systems by gluing them together with pseudo-file systems. These + pseudo-file systems provide for potential gaps in the pathnames + between real file systems. + + + +Haynes & Noveck Standards Track [Page 10] + +RFC 7530 NFSv4 March 2015 + + +1.4.3.1. Filehandle Types + + In previous versions of the NFS protocol, the filehandle provided by + the server was guaranteed to be valid or persistent for the lifetime + of the file system object to which it referred. For some server + implementations, this persistence requirement has been difficult to + meet. For the NFSv4 protocol, this requirement has been relaxed by + introducing another type of filehandle -- volatile. With persistent + and volatile filehandle types, the server implementation can match + the abilities of the file system at the server along with the + operating environment. The client will have knowledge of the type of + filehandle being provided by the server and can be prepared to deal + with the semantics of each. + +1.4.3.2. Attribute Types + + The NFSv4 protocol has a rich and extensible file object attribute + structure, which is divided into REQUIRED, RECOMMENDED, and named + attributes (see Section 5). + + Several (but not all) of the REQUIRED attributes are derived from the + attributes of NFSv3 (see the definition of the fattr3 data type in + [RFC1813]). An example of a REQUIRED attribute is the file object's + type (Section 5.8.1.2) so that regular files can be distinguished + from directories (also known as folders in some operating + environments) and other types of objects. REQUIRED attributes are + discussed in Section 5.1. + + An example of the RECOMMENDED attributes is an acl (Section 6.2.1). + This attribute defines an Access Control List (ACL) on a file object. + An ACL provides file access control beyond the model used in NFSv3. + The ACL definition allows for specification of specific sets of + permissions for individual users and groups. In addition, ACL + inheritance allows propagation of access permissions and restriction + down a directory tree as file system objects are created. + RECOMMENDED attributes are discussed in Section 5.2. + + A named attribute is an opaque byte stream that is associated with a + directory or file and referred to by a string name. Named attributes + are meant to be used by client applications as a method to associate + application-specific data with a regular file or directory. NFSv4.1 + modifies named attributes relative to NFSv4.0 by tightening the + allowed operations in order to prevent the development of + non-interoperable implementations. Named attributes are discussed in + Section 5.3. + + + + + + +Haynes & Noveck Standards Track [Page 11] + +RFC 7530 NFSv4 March 2015 + + +1.4.3.3. Multi-Server Namespace + + A single-server namespace is the file system hierarchy that the + server presents for remote access. It is a proper subset of all the + file systems available locally. NFSv4 contains a number of features + to allow implementation of namespaces that cross server boundaries + and that allow and facilitate a non-disruptive transfer of support + for individual file systems between servers. They are all based upon + attributes that allow one file system to specify alternative or new + locations for that file system. That is, just as a client might + traverse across local file systems on a single server, it can now + traverse to a remote file system on a different server. + + These attributes may be used together with the concept of absent file + systems, which provide specifications for additional locations but no + actual file system content. This allows a number of important + facilities: + + o Location attributes may be used with absent file systems to + implement referrals whereby one server may direct the client to a + file system provided by another server. This allows extensive + multi-server namespaces to be constructed. + + o Location attributes may be provided for present file systems to + provide the locations of alternative file system instances or + replicas to be used in the event that the current file system + instance becomes unavailable. + + o Location attributes may be provided when a previously present file + system becomes absent. This allows non-disruptive migration of + file systems to alternative servers. + +1.4.4. OPEN and CLOSE + + The NFSv4 protocol introduces OPEN and CLOSE operations. The OPEN + operation provides a single point where file lookup, creation, and + share semantics (see Section 9.9) can be combined. The CLOSE + operation also provides for the release of state accumulated by OPEN. + +1.4.5. File Locking + + With the NFSv4 protocol, the support for byte-range file locking is + part of the NFS protocol. The file locking support is structured so + that an RPC callback mechanism is not required. This is a departure + from the previous versions of the NFS file locking protocol, Network + Lock Manager (NLM) [RFC1813]. The state associated with file locks + is maintained at the server under a lease-based model. The server + defines a single lease period for all state held by an NFS client. + + + +Haynes & Noveck Standards Track [Page 12] + +RFC 7530 NFSv4 March 2015 + + + If the client does not renew its lease within the defined period, all + state associated with the client's lease may be released by the + server. The client may renew its lease by use of the RENEW operation + or implicitly by use of other operations (primarily READ). + +1.4.6. Client Caching and Delegation + + The file, attribute, and directory caching for the NFSv4 protocol is + similar to previous versions. Attributes and directory information + are cached for a duration determined by the client. At the end of a + predefined timeout, the client will query the server to see if the + related file system object has been updated. + + For file data, the client checks its cache validity when the file is + opened. A query is sent to the server to determine if the file has + been changed. Based on this information, the client determines if + the data cache for the file should be kept or released. Also, when + the file is closed, any modified data is written to the server. + + If an application wants to serialize access to file data, file + locking of the file data ranges in question should be used. + + The major addition to NFSv4 in the area of caching is the ability of + the server to delegate certain responsibilities to the client. When + the server grants a delegation for a file to a client, the client is + guaranteed certain semantics with respect to the sharing of that file + with other clients. At OPEN, the server may provide the client + either a read (OPEN_DELEGATE_READ) or a write (OPEN_DELEGATE_WRITE) + delegation for the file (see Section 10.4). If the client is granted + an OPEN_DELEGATE_READ delegation, it is assured that no other client + has the ability to write to the file for the duration of the + delegation. If the client is granted an OPEN_DELEGATE_WRITE + delegation, the client is assured that no other client has read or + write access to the file. + + Delegations can be recalled by the server. If another client + requests access to the file in such a way that the access conflicts + with the granted delegation, the server is able to notify the initial + client and recall the delegation. This requires that a callback path + exist between the server and client. If this callback path does not + exist, then delegations cannot be granted. The essence of a + delegation is that it allows the client to locally service operations + such as OPEN, CLOSE, LOCK, LOCKU, READ, or WRITE without immediate + interaction with the server. + + + + + + + +Haynes & Noveck Standards Track [Page 13] + +RFC 7530 NFSv4 March 2015 + + +1.5. General Definitions + + The following definitions are provided for the purpose of providing + an appropriate context for the reader. + + Absent File System: A file system is "absent" when a namespace + component does not have a backing file system. + + Anonymous Stateid: The Anonymous Stateid is a special locking object + and is defined in Section 9.1.4.3. + + Byte: In this document, a byte is an octet, i.e., a datum exactly + 8 bits in length. + + Client: The client is the entity that accesses the NFS server's + resources. The client may be an application that contains the + logic to access the NFS server directly. The client may also be + the traditional operating system client that provides remote file + system services for a set of applications. + + With reference to byte-range locking, the client is also the + entity that maintains a set of locks on behalf of one or more + applications. This client is responsible for crash or failure + recovery for those locks it manages. + + Note that multiple clients may share the same transport and + connection, and multiple clients may exist on the same network + node. + + Client ID: The client ID is a 64-bit quantity used as a unique, + shorthand reference to a client-supplied verifier and ID. The + server is responsible for supplying the client ID. + + File System: The file system is the collection of objects on a + server that share the same fsid attribute (see Section 5.8.1.9). + + Lease: A lease is an interval of time defined by the server for + which the client is irrevocably granted a lock. At the end of a + lease period the lock may be revoked if the lease has not been + extended. The lock must be revoked if a conflicting lock has been + granted after the lease interval. + + All leases granted by a server have the same fixed duration. Note + that the fixed interval duration was chosen to alleviate the + expense a server would have in maintaining state about variable- + length leases across server failures. + + + + + +Haynes & Noveck Standards Track [Page 14] + +RFC 7530 NFSv4 March 2015 + + + Lock: The term "lock" is used to refer to record (byte-range) locks + as well as share reservations unless specifically stated + otherwise. + + Lock-Owner: Each byte-range lock is associated with a specific + lock-owner and an open-owner. The lock-owner consists of a + client ID and an opaque owner string. The client presents this to + the server to establish the ownership of the byte-range lock as + needed. + + Open-Owner: Each open file is associated with a specific open-owner, + which consists of a client ID and an opaque owner string. The + client presents this to the server to establish the ownership of + the open as needed. + + READ Bypass Stateid: The READ Bypass Stateid is a special locking + object and is defined in Section 9.1.4.3. + + Server: The "server" is the entity responsible for coordinating + client access to a set of file systems. + + Stable Storage: NFSv4 servers must be able to recover without data + loss from multiple power failures (including cascading power + failures, that is, several power failures in quick succession), + operating system failures, and hardware failure of components + other than the storage medium itself (for example, disk, + non-volatile RAM). + + Some examples of stable storage that are allowable for an NFS + server include: + + (1) Media commit of data. That is, the modified data has been + successfully written to the disk media -- for example, the + disk platter. + + (2) An immediate reply disk drive with battery-backed on-drive + intermediate storage or uninterruptible power system (UPS). + + (3) Server commit of data with battery-backed intermediate + storage and recovery software. + + (4) Cache commit with UPS and recovery software. + + + + + + + + + +Haynes & Noveck Standards Track [Page 15] + +RFC 7530 NFSv4 March 2015 + + + Stateid: A stateid is a 128-bit quantity returned by a server that + uniquely identifies the open and locking states provided by the + server for a specific open-owner or lock-owner/open-owner pair for + a specific file and type of lock. + + Verifier: A verifier is a 64-bit quantity generated by the client + that the server can use to determine if the client has restarted + and lost all previous lock state. + +1.6. Changes since RFC 3530 + + The main changes from RFC 3530 [RFC3530] are: + + o The XDR definition has been moved to a companion document + [RFC7531]. + + o The IETF intellectual property statements were updated to the + latest version. + + o There is a restructured and more complete explanation of multi- + server namespace features. + + o The handling of domain names was updated to reflect + Internationalized Domain Names in Applications (IDNA) [RFC5891]. + + o The previously required LIPKEY and SPKM-3 security mechanisms have + been removed. + + o Some clarification was provided regarding a client re-establishing + callback information to the new server if state has been migrated. + + o A third edge case was added for courtesy locks and network + partitions. + + o The definition of stateid was strengthened. + +1.7. Changes between RFC 3010 and RFC 3530 + + The definition of the NFSv4 protocol in [RFC3530] replaced and + obsoleted the definition present in [RFC3010]. While portions of the + two documents remained the same, there were substantive changes in + others. The changes made between [RFC3010] and [RFC3530] reflect + implementation experience and further review of the protocol. + + + + + + + + +Haynes & Noveck Standards Track [Page 16] + +RFC 7530 NFSv4 March 2015 + + + The following list is not inclusive of all changes but presents some + of the most notable changes or additions made: + + o The state model has added an open_owner4 identifier. This was + done to accommodate POSIX-based clients and the model they use for + file locking. For POSIX clients, an open_owner4 would correspond + to a file descriptor potentially shared amongst a set of processes + and the lock_owner4 identifier would correspond to a process that + is locking a file. + + o Added clarifications and error conditions for the handling of the + owner and group attributes. Since these attributes are string + based (as opposed to the numeric uid/gid of previous versions of + NFS), translations may not be available and hence the changes + made. + + o Added clarifications for the ACL and mode attributes to address + evaluation and partial support. + + o For identifiers that are defined as XDR opaque, set limits on + their size. + + o Added the mounted_on_fileid attribute to allow POSIX clients to + correctly construct local mounts. + + o Modified the SETCLIENTID/SETCLIENTID_CONFIRM operations to deal + correctly with confirmation details along with adding the ability + to specify new client callback information. Also added + clarification of the callback information itself. + + o Added a new operation RELEASE_LOCKOWNER to enable notifying the + server that a lock_owner4 will no longer be used by the client. + + o Added RENEW operation changes to identify the client correctly and + allow for additional error returns. + + o Verified error return possibilities for all operations. + + o Removed use of the pathname4 data type from LOOKUP and OPEN in + favor of having the client construct a sequence of LOOKUP + operations to achieve the same effect. + + + + + + + + + + +Haynes & Noveck Standards Track [Page 17] + +RFC 7530 NFSv4 March 2015 + + +2. Protocol Data Types + + The syntax and semantics to describe the data types of the NFSv4 + protocol are defined in the XDR [RFC4506] and RPC [RFC5531] + documents. The next sections build upon the XDR data types to define + types and structures specific to this protocol. As a reminder, the + size constants and authoritative definitions can be found in + [RFC7531]. + +2.1. Basic Data Types + + Table 1 lists the base NFSv4 data types. + + +-----------------+-------------------------------------------------+ + | Data Type | Definition | + +-----------------+-------------------------------------------------+ + | int32_t | typedef int int32_t; | + | | | + | uint32_t | typedef unsigned int uint32_t; | + | | | + | int64_t | typedef hyper int64_t; | + | | | + | uint64_t | typedef unsigned hyper uint64_t; | + | | | + | attrlist4 | typedef opaque attrlist4<>; | + | | | + | | Used for file/directory attributes. | + | | | + | bitmap4 | typedef uint32_t bitmap4<>; | + | | | + | | Used in attribute array encoding. | + | | | + | changeid4 | typedef uint64_t changeid4; | + | | | + | | Used in the definition of change_info4. | + | | | + | clientid4 | typedef uint64_t clientid4; | + | | | + | | Shorthand reference to client identification. | + | | | + | count4 | typedef uint32_t count4; | + | | | + | | Various count parameters (READ, WRITE, COMMIT). | + | | | + | length4 | typedef uint64_t length4; | + | | | + | | Describes LOCK lengths. | + | | | + + + +Haynes & Noveck Standards Track [Page 18] + +RFC 7530 NFSv4 March 2015 + + + | mode4 | typedef uint32_t mode4; | + | | | + | | Mode attribute data type. | + | | | + | nfs_cookie4 | typedef uint64_t nfs_cookie4; | + | | | + | | Opaque cookie value for READDIR. | + | | | + | nfs_fh4 | typedef opaque nfs_fh4; | + | | | + | | Filehandle definition. | + | | | + | nfs_ftype4 | enum nfs_ftype4; | + | | | + | | Various defined file types. | + | | | + | nfsstat4 | enum nfsstat4; | + | | | + | | Return value for operations. | + | | | + | nfs_lease4 | typedef uint32_t nfs_lease4; | + | | | + | | Duration of a lease in seconds. | + | | | + | offset4 | typedef uint64_t offset4; | + | | | + | | Various offset designations (READ, WRITE, LOCK, | + | | COMMIT). | + | | | + | qop4 | typedef uint32_t qop4; | + | | | + | | Quality of protection designation in SECINFO. | + | | | + | sec_oid4 | typedef opaque sec_oid4<>; | + | | | + | | Security Object Identifier. The sec_oid4 data | + | | type is not really opaque. Instead, it | + | | contains an ASN.1 OBJECT IDENTIFIER as used by | + | | GSS-API in the mech_type argument to | + | | GSS_Init_sec_context. See [RFC2743] for | + | | details. | + | | | + | seqid4 | typedef uint32_t seqid4; | + | | | + | | Sequence identifier used for file locking. | + | | | + + + + + +Haynes & Noveck Standards Track [Page 19] + +RFC 7530 NFSv4 March 2015 + + + | utf8string | typedef opaque utf8string<>; | + | | | + | | UTF-8 encoding for strings. | + | | | + | utf8str_cis | typedef utf8string utf8str_cis; | + | | | + | | Case-insensitive UTF-8 string. | + | | | + | utf8str_cs | typedef utf8string utf8str_cs; | + | | | + | | Case-sensitive UTF-8 string. | + | | | + | utf8str_mixed | typedef utf8string utf8str_mixed; | + | | | + | | UTF-8 strings with a case-sensitive prefix and | + | | a case-insensitive suffix. | + | | | + | component4 | typedef utf8str_cs component4; | + | | | + | | Represents pathname components. | + | | | + | linktext4 | typedef opaque linktext4<>; | + | | | + | | Symbolic link contents ("symbolic link" is | + | | defined in an Open Group [openg_symlink] | + | | standard). | + | | | + | ascii_REQUIRED4 | typedef utf8string ascii_REQUIRED4; | + | | | + | | String is sent as ASCII and thus is | + | | automatically UTF-8. | + | | | + | pathname4 | typedef component4 pathname4<>; | + | | | + | | Represents pathname for fs_locations. | + | | | + | nfs_lockid4 | typedef uint64_t nfs_lockid4; | + | | | + | verifier4 | typedef opaque verifier4[NFS4_VERIFIER_SIZE]; | + | | | + | | Verifier used for various operations (COMMIT, | + | | CREATE, OPEN, READDIR, WRITE) | + | | NFS4_VERIFIER_SIZE is defined as 8. | + +-----------------+-------------------------------------------------+ + + Table 1: Base NFSv4 Data Types + + + + + +Haynes & Noveck Standards Track [Page 20] + +RFC 7530 NFSv4 March 2015 + + +2.2. Structured Data Types + +2.2.1. nfstime4 + + struct nfstime4 { + int64_t seconds; + uint32_t nseconds; + }; + + The nfstime4 structure gives the number of seconds and nanoseconds + since midnight or 0 hour January 1, 1970 Coordinated Universal Time + (UTC). Values greater than zero for the seconds field denote dates + after the 0 hour January 1, 1970. Values less than zero for the + seconds field denote dates before the 0 hour January 1, 1970. In + both cases, the nseconds field is to be added to the seconds field + for the final time representation. For example, if the time to be + represented is one-half second before 0 hour January 1, 1970, the + seconds field would have a value of negative one (-1) and the + nseconds fields would have a value of one-half second (500000000). + Values greater than 999,999,999 for nseconds are considered invalid. + + This data type is used to pass time and date information. A server + converts to and from its local representation of time when processing + time values, preserving as much accuracy as possible. If the + precision of timestamps stored for a file system object is less than + defined, loss of precision can occur. An adjunct time maintenance + protocol is recommended to reduce client and server time skew. + +2.2.2. time_how4 + + enum time_how4 { + SET_TO_SERVER_TIME4 = 0, + SET_TO_CLIENT_TIME4 = 1 + }; + +2.2.3. settime4 + + union settime4 switch (time_how4 set_it) { + case SET_TO_CLIENT_TIME4: + nfstime4 time; + default: + void; + }; + + The above definitions are used as the attribute definitions to set + time values. If set_it is SET_TO_SERVER_TIME4, then the server uses + its local representation of time for the time value. + + + + +Haynes & Noveck Standards Track [Page 21] + +RFC 7530 NFSv4 March 2015 + + +2.2.4. specdata4 + + struct specdata4 { + uint32_t specdata1; /* major device number */ + uint32_t specdata2; /* minor device number */ + }; + + This data type represents additional information for the device file + types NF4CHR and NF4BLK. + +2.2.5. fsid4 + + struct fsid4 { + uint64_t major; + uint64_t minor; + }; + + This type is the file system identifier that is used as a REQUIRED + attribute. + +2.2.6. fs_location4 + + struct fs_location4 { + utf8str_cis server<>; + pathname4 rootpath; + }; + +2.2.7. fs_locations4 + + struct fs_locations4 { + pathname4 fs_root; + fs_location4 locations<>; + }; + + The fs_location4 and fs_locations4 data types are used for the + fs_locations RECOMMENDED attribute, which is used for migration and + replication support. + +2.2.8. fattr4 + + struct fattr4 { + bitmap4 attrmask; + attrlist4 attr_vals; + }; + + The fattr4 structure is used to represent file and directory + attributes. + + + + +Haynes & Noveck Standards Track [Page 22] + +RFC 7530 NFSv4 March 2015 + + + The bitmap is a counted array of 32-bit integers used to contain bit + values. The position of the integer in the array that contains bit n + can be computed from the expression (n / 32), and its bit within that + integer is (n mod 32). + + 0 1 + +-----------+-----------+-----------+-- + | count | 31 .. 0 | 63 .. 32 | + +-----------+-----------+-----------+-- + +2.2.9. change_info4 + + struct change_info4 { + bool atomic; + changeid4 before; + changeid4 after; + }; + + This structure is used with the CREATE, LINK, REMOVE, and RENAME + operations to let the client know the value of the change attribute + for the directory in which the target file system object resides. + +2.2.10. clientaddr4 + + struct clientaddr4 { + /* see struct rpcb in RFC 1833 */ + string r_netid<>; /* network id */ + string r_addr<>; /* universal address */ + }; + + The clientaddr4 structure is used as part of the SETCLIENTID + operation, either (1) to specify the address of the client that is + using a client ID or (2) as part of the callback registration. The + r_netid and r_addr fields respectively contain a network id and + universal address. The network id and universal address concepts, + together with formats for TCP over IPv4 and TCP over IPv6, are + defined in [RFC5665], specifically Tables 2 and 3 and + Sections 5.2.3.3 and 5.2.3.4. + +2.2.11. cb_client4 + + struct cb_client4 { + unsigned int cb_program; + clientaddr4 cb_location; + }; + + This structure is used by the client to inform the server of its + callback address; it includes the program number and client address. + + + +Haynes & Noveck Standards Track [Page 23] + +RFC 7530 NFSv4 March 2015 + + +2.2.12. nfs_client_id4 + + struct nfs_client_id4 { + verifier4 verifier; + opaque id; + }; + + This structure is part of the arguments to the SETCLIENTID operation. + +2.2.13. open_owner4 + + struct open_owner4 { + clientid4 clientid; + opaque owner; + }; + + This structure is used to identify the owner of open state. + +2.2.14. lock_owner4 + + struct lock_owner4 { + clientid4 clientid; + opaque owner; + }; + + This structure is used to identify the owner of file locking state. + +2.2.15. open_to_lock_owner4 + + struct open_to_lock_owner4 { + seqid4 open_seqid; + stateid4 open_stateid; + seqid4 lock_seqid; + lock_owner4 lock_owner; + }; + + This structure is used for the first LOCK operation done for an + open_owner4. It provides both the open_stateid and lock_owner such + that the transition is made from a valid open_stateid sequence to + that of the new lock_stateid sequence. Using this mechanism avoids + the confirmation of the lock_owner/lock_seqid pair since it is tied + to established state in the form of the open_stateid/open_seqid. + + + + + + + + + +Haynes & Noveck Standards Track [Page 24] + +RFC 7530 NFSv4 March 2015 + + +2.2.16. stateid4 + + struct stateid4 { + uint32_t seqid; + opaque other[NFS4_OTHER_SIZE]; + }; + + This structure is used for the various state-sharing mechanisms + between the client and server. For the client, this data structure + is read-only. The server is required to increment the seqid field + monotonically at each transition of the stateid. This is important + since the client will inspect the seqid in OPEN stateids to determine + the order of OPEN processing done by the server. + +3. RPC and Security Flavor + + The NFSv4 protocol is an RPC application that uses RPC version 2 and + the XDR as defined in [RFC5531] and [RFC4506]. The RPCSEC_GSS + security flavors as defined in version 1 ([RFC2203]) and version 2 + ([RFC5403]) MUST be implemented as the mechanism to deliver stronger + security for the NFSv4 protocol. However, deployment of RPCSEC_GSS + is optional. + +3.1. Ports and Transports + + Historically, NFSv2 and NFSv3 servers have resided on port 2049. The + registered port 2049 [RFC3232] for the NFS protocol SHOULD be the + default configuration. Using the registered port for NFS services + means the NFS client will not need to use the RPC binding protocols + as described in [RFC1833]; this will allow NFS to transit firewalls. + + Where an NFSv4 implementation supports operation over the IP network + protocol, the supported transport layer between NFS and IP MUST be an + IETF standardized transport protocol that is specified to avoid + network congestion; such transports include TCP and the Stream + Control Transmission Protocol (SCTP). To enhance the possibilities + for interoperability, an NFSv4 implementation MUST support operation + over the TCP transport protocol. + + If TCP is used as the transport, the client and server SHOULD use + persistent connections. This will prevent the weakening of TCP's + congestion control via short-lived connections and will improve + performance for the Wide Area Network (WAN) environment by + eliminating the need for SYN handshakes. + + As noted in Section 19, the authentication model for NFSv4 has moved + from machine-based to principal-based. However, this modification of + the authentication model does not imply a technical requirement to + + + +Haynes & Noveck Standards Track [Page 25] + +RFC 7530 NFSv4 March 2015 + + + move the TCP connection management model from whole machine-based to + one based on a per-user model. In particular, NFS over TCP client + implementations have traditionally multiplexed traffic for multiple + users over a common TCP connection between an NFS client and server. + This has been true, regardless of whether the NFS client is using + AUTH_SYS, AUTH_DH, RPCSEC_GSS, or any other flavor. Similarly, NFS + over TCP server implementations have assumed such a model and thus + scale the implementation of TCP connection management in proportion + to the number of expected client machines. It is intended that NFSv4 + will not modify this connection management model. NFSv4 clients that + violate this assumption can expect scaling issues on the server and + hence reduced service. + +3.1.1. Client Retransmission Behavior + + When processing an NFSv4 request received over a reliable transport + such as TCP, the NFSv4 server MUST NOT silently drop the request, + except if the established transport connection has been broken. + Given such a contract between NFSv4 clients and servers, clients MUST + NOT retry a request unless one or both of the following are true: + + o The transport connection has been broken + + o The procedure being retried is the NULL procedure + + Since reliable transports, such as TCP, do not always synchronously + inform a peer when the other peer has broken the connection (for + example, when an NFS server reboots), the NFSv4 client may want to + actively "probe" the connection to see if has been broken. Use of + the NULL procedure is one recommended way to do so. So, when a + client experiences a remote procedure call timeout (of some arbitrary + implementation-specific amount), rather than retrying the remote + procedure call, it could instead issue a NULL procedure call to the + server. If the server has died, the transport connection break will + eventually be indicated to the NFSv4 client. The client can then + reconnect, and then retry the original request. If the NULL + procedure call gets a response, the connection has not broken. The + client can decide to wait longer for the original request's response, + or it can break the transport connection and reconnect before + re-sending the original request. + + For callbacks from the server to the client, the same rules apply, + but the server doing the callback becomes the client, and the client + receiving the callback becomes the server. + + + + + + + +Haynes & Noveck Standards Track [Page 26] + +RFC 7530 NFSv4 March 2015 + + +3.2. Security Flavors + + Traditional RPC implementations have included AUTH_NONE, AUTH_SYS, + AUTH_DH, and AUTH_KRB4 as security flavors. With [RFC2203], an + additional security flavor of RPCSEC_GSS has been introduced, which + uses the functionality of GSS-API [RFC2743]. This allows for the use + of various security mechanisms by the RPC layer without the + additional implementation overhead of adding RPC security flavors. + For NFSv4, the RPCSEC_GSS security flavor MUST be used to enable the + mandatory-to-implement security mechanism. Other flavors, such as + AUTH_NONE, AUTH_SYS, and AUTH_DH, MAY be implemented as well. + +3.2.1. Security Mechanisms for NFSv4 + + RPCSEC_GSS, via GSS-API, supports multiple mechanisms that provide + security services. For interoperability, NFSv4 clients and servers + MUST support the Kerberos V5 security mechanism. + + The use of RPCSEC_GSS requires selection of mechanism, quality of + protection (QOP), and service (authentication, integrity, privacy). + For the mandated security mechanisms, NFSv4 specifies that a QOP of + zero is used, leaving it up to the mechanism or the mechanism's + configuration to map QOP zero to an appropriate level of protection. + Each mandated mechanism specifies a minimum set of cryptographic + algorithms for implementing integrity and privacy. NFSv4 clients and + servers MUST be implemented on operating environments that comply + with the required cryptographic algorithms of each required + mechanism. + +3.2.1.1. Kerberos V5 as a Security Triple + + The Kerberos V5 GSS-API mechanism as described in [RFC4121] MUST be + implemented with the RPCSEC_GSS services as specified in Table 2. + Both client and server MUST support each of the pseudo-flavors. + + +--------+-------+----------------------+-----------------------+ + | Number | Name | Mechanism's OID | RPCSEC_GSS service | + +--------+-------+----------------------+-----------------------+ + | 390003 | krb5 | 1.2.840.113554.1.2.2 | rpc_gss_svc_none | + | 390004 | krb5i | 1.2.840.113554.1.2.2 | rpc_gss_svc_integrity | + | 390005 | krb5p | 1.2.840.113554.1.2.2 | rpc_gss_svc_privacy | + +--------+-------+----------------------+-----------------------+ + + Table 2: Mapping Pseudo-Flavor to Service + + Note that the pseudo-flavor is presented here as a mapping aid to the + implementer. Because this NFS protocol includes a method to + negotiate security and it understands the GSS-API mechanism, the + + + +Haynes & Noveck Standards Track [Page 27] + +RFC 7530 NFSv4 March 2015 + + + pseudo-flavor is not needed. The pseudo-flavor is needed for NFSv3 + since the security negotiation is done via the MOUNT protocol as + described in [RFC2623]. + + At the time this document was specified, the Advanced Encryption + Standard (AES) with HMAC-SHA1 was a required algorithm set for + Kerberos V5. In contrast, when NFSv4.0 was first specified in + [RFC3530], weaker algorithm sets were REQUIRED for Kerberos V5, and + were REQUIRED in the NFSv4.0 specification, because the Kerberos V5 + specification at the time did not specify stronger algorithms. The + NFSv4 specification does not specify required algorithms for Kerberos + V5, and instead, the implementer is expected to track the evolution + of the Kerberos V5 standard if and when stronger algorithms are + specified. + +3.2.1.1.1. Security Considerations for Cryptographic Algorithms in + Kerberos V5 + + When deploying NFSv4, the strength of the security achieved depends + on the existing Kerberos V5 infrastructure. The algorithms of + Kerberos V5 are not directly exposed to or selectable by the client + or server, so there is some due diligence required by the user of + NFSv4 to ensure that security is acceptable where needed. Guidance + is provided in [RFC6649] as to why weak algorithms should be disabled + by default. + +3.3. Security Negotiation + + With the NFSv4 server potentially offering multiple security + mechanisms, the client needs a method to determine or negotiate which + mechanism is to be used for its communication with the server. The + NFS server can have multiple points within its file system namespace + that are available for use by NFS clients. In turn, the NFS server + can be configured such that each of these entry points can have + different or multiple security mechanisms in use. + + The security negotiation between client and server SHOULD be done + with a secure channel to eliminate the possibility of a third party + intercepting the negotiation sequence and forcing the client and + server to choose a lower level of security than required or desired. + See Section 19 for further discussion. + + + + + + + + + + +Haynes & Noveck Standards Track [Page 28] + +RFC 7530 NFSv4 March 2015 + + +3.3.1. SECINFO + + The SECINFO operation will allow the client to determine, on a + per-filehandle basis, what security triple (see [RFC2743] and + Section 16.31.4) is to be used for server access. In general, the + client will not have to use the SECINFO operation, except during + initial communication with the server or when the client encounters a + new security policy as the client navigates the namespace. Either + condition will force the client to negotiate a new security triple. + +3.3.2. Security Error + + Based on the assumption that each NFSv4 client and server MUST + support a minimum set of security (i.e., Kerberos V5 under + RPCSEC_GSS), the NFS client will start its communication with the + server with one of the minimal security triples. During + communication with the server, the client can receive an NFS error of + NFS4ERR_WRONGSEC. This error allows the server to notify the client + that the security triple currently being used is not appropriate for + access to the server's file system resources. The client is then + responsible for determining what security triples are available at + the server and choosing one that is appropriate for the client. See + Section 16.31 for further discussion of how the client will respond + to the NFS4ERR_WRONGSEC error and use SECINFO. + +3.3.3. Callback RPC Authentication + + Except as noted elsewhere in this section, the callback RPC + (described later) MUST mutually authenticate the NFS server to the + principal that acquired the client ID (also described later), using + the security flavor of the original SETCLIENTID operation used. + + For AUTH_NONE, there are no principals, so this is a non-issue. + + AUTH_SYS has no notions of mutual authentication or a server + principal, so the callback from the server simply uses the AUTH_SYS + credential that the user used when he set up the delegation. + + For AUTH_DH, one commonly used convention is that the server uses the + credential corresponding to this AUTH_DH principal: + + unix.host@domain + + where host and domain are variables corresponding to the name of the + server host and directory services domain in which it lives, such as + a Network Information System domain or a DNS domain. + + + + + +Haynes & Noveck Standards Track [Page 29] + +RFC 7530 NFSv4 March 2015 + + + Regardless of what security mechanism under RPCSEC_GSS is being used, + the NFS server MUST identify itself in GSS-API via a + GSS_C_NT_HOSTBASED_SERVICE name type. GSS_C_NT_HOSTBASED_SERVICE + names are of the form: + + service@hostname + + For NFS, the "service" element is: + + nfs + + Implementations of security mechanisms will convert nfs@hostname to + various different forms. For Kerberos V5, the following form is + RECOMMENDED: + + nfs/hostname + + For Kerberos V5, nfs/hostname would be a server principal in the + Kerberos Key Distribution Center database. This is the same + principal the client acquired a GSS-API context for when it issued + the SETCLIENTID operation; therefore, the realm name for the server + principal must be the same for the callback as it was for the + SETCLIENTID. + +4. Filehandles + + The filehandle in the NFS protocol is a per-server unique identifier + for a file system object. The contents of the filehandle are opaque + to the client. Therefore, the server is responsible for translating + the filehandle to an internal representation of the file system + object. + +4.1. Obtaining the First Filehandle + + The operations of the NFS protocol are defined in terms of one or + more filehandles. Therefore, the client needs a filehandle to + initiate communication with the server. With the NFSv2 protocol + [RFC1094] and the NFSv3 protocol [RFC1813], there exists an ancillary + protocol to obtain this first filehandle. The MOUNT protocol, RPC + program number 100005, provides the mechanism of translating a + string-based file system pathname to a filehandle that can then be + used by the NFS protocols. + + The MOUNT protocol has deficiencies in the area of security and use + via firewalls. This is one reason that the use of the public + filehandle was introduced in [RFC2054] and [RFC2055]. With the use + of the public filehandle in combination with the LOOKUP operation in + + + + +Haynes & Noveck Standards Track [Page 30] + +RFC 7530 NFSv4 March 2015 + + + the NFSv2 and NFSv3 protocols, it has been demonstrated that the + MOUNT protocol is unnecessary for viable interaction between the NFS + client and server. + + Therefore, the NFSv4 protocol will not use an ancillary protocol for + translation from string-based pathnames to a filehandle. Two special + filehandles will be used as starting points for the NFS client. + +4.1.1. Root Filehandle + + The first of the special filehandles is the root filehandle. The + root filehandle is the "conceptual" root of the file system namespace + at the NFS server. The client uses or starts with the root + filehandle by employing the PUTROOTFH operation. The PUTROOTFH + operation instructs the server to set the current filehandle to the + root of the server's file tree. Once this PUTROOTFH operation is + used, the client can then traverse the entirety of the server's file + tree with the LOOKUP operation. A complete discussion of the server + namespace is in Section 7. + +4.1.2. Public Filehandle + + The second special filehandle is the public filehandle. Unlike the + root filehandle, the public filehandle may be bound or represent an + arbitrary file system object at the server. The server is + responsible for this binding. It may be that the public filehandle + and the root filehandle refer to the same file system object. + However, it is up to the administrative software at the server and + the policies of the server administrator to define the binding of the + public filehandle and server file system object. The client may not + make any assumptions about this binding. The client uses the public + filehandle via the PUTPUBFH operation. + +4.2. Filehandle Types + + In the NFSv2 and NFSv3 protocols, there was one type of filehandle + with a single set of semantics, of which the primary one was that it + was persistent across a server reboot. As such, this type of + filehandle is termed "persistent" in NFSv4. The semantics of a + persistent filehandle remain the same as before. A new type of + filehandle introduced in NFSv4 is the volatile filehandle, which + attempts to accommodate certain server environments. + + The volatile filehandle type was introduced to address server + functionality or implementation issues that make correct + implementation of a persistent filehandle infeasible. Some server + environments do not provide a file system level invariant that can be + used to construct a persistent filehandle. The underlying server + + + +Haynes & Noveck Standards Track [Page 31] + +RFC 7530 NFSv4 March 2015 + + + file system may not provide the invariant, or the server's file + system programming interfaces may not provide access to the needed + invariant. Volatile filehandles may ease the implementation of + server functionality, such as hierarchical storage management or file + system reorganization or migration. However, the volatile filehandle + increases the implementation burden for the client. + + Since the client will need to handle persistent and volatile + filehandles differently, a file attribute is defined that may be used + by the client to determine the filehandle types being returned by the + server. + +4.2.1. General Properties of a Filehandle + + The filehandle contains all the information the server needs to + distinguish an individual file. To the client, the filehandle is + opaque. The client stores filehandles for use in a later request and + can compare two filehandles from the same server for equality by + doing a byte-by-byte comparison. However, the client MUST NOT + otherwise interpret the contents of filehandles. If two filehandles + from the same server are equal, they MUST refer to the same file. + However, it is not required that two different filehandles refer to + different file system objects. Servers SHOULD try to maintain a + one-to-one correspondence between filehandles and file system objects + but there may be situations in which the mapping is not one-to-one. + Clients MUST use filehandle comparisons only to improve performance, + not for correct behavior. All clients need to be prepared for + situations in which it cannot be determined whether two different + filehandles denote the same object and in such cases need to avoid + assuming that objects denoted are different, as this might cause + incorrect behavior. Further discussion of filehandle and attribute + comparison in the context of data caching is presented in + Section 10.3.4. + + As an example, in the case that two different pathnames when + traversed at the server terminate at the same file system object, the + server SHOULD return the same filehandle for each path. This can + occur if a hard link is used to create two filenames that refer to + the same underlying file object and associated data. For example, if + paths /a/b/c and /a/d/c refer to the same file, the server SHOULD + return the same filehandle for both pathname traversals. + +4.2.2. Persistent Filehandle + + A persistent filehandle is defined as having a fixed value for the + lifetime of the file system object to which it refers. Once the + server creates the filehandle for a file system object, the server + MUST accept the same filehandle for the object for the lifetime of + + + +Haynes & Noveck Standards Track [Page 32] + +RFC 7530 NFSv4 March 2015 + + + the object. If the server restarts or reboots, the NFS server must + honor the same filehandle value as it did in the server's previous + instantiation. Similarly, if the file system is migrated, the new + NFS server must honor the same filehandle as the old NFS server. + + The persistent filehandle will become stale or invalid when the file + system object is removed. When the server is presented with a + persistent filehandle that refers to a deleted object, it MUST return + an error of NFS4ERR_STALE. A filehandle may become stale when the + file system containing the object is no longer available. The file + system may become unavailable if it exists on removable media and the + media is no longer available at the server, or if the file system in + whole has been destroyed, or if the file system has simply been + removed from the server's namespace (i.e., unmounted in a UNIX + environment). + +4.2.3. Volatile Filehandle + + A volatile filehandle does not share the same longevity + characteristics of a persistent filehandle. The server may determine + that a volatile filehandle is no longer valid at many different + points in time. If the server can definitively determine that a + volatile filehandle refers to an object that has been removed, the + server should return NFS4ERR_STALE to the client (as is the case for + persistent filehandles). In all other cases where the server + determines that a volatile filehandle can no longer be used, it + should return an error of NFS4ERR_FHEXPIRED. + + The REQUIRED attribute "fh_expire_type" is used by the client to + determine what type of filehandle the server is providing for a + particular file system. This attribute is a bitmask with the + following values: + + FH4_PERSISTENT: The value of FH4_PERSISTENT is used to indicate a + persistent filehandle, which is valid until the object is removed + from the file system. The server will not return + NFS4ERR_FHEXPIRED for this filehandle. FH4_PERSISTENT is defined + as a value in which none of the bits specified below are set. + + FH4_VOLATILE_ANY: The filehandle may expire at any time, except as + specifically excluded (i.e., FH4_NOEXPIRE_WITH_OPEN). + + FH4_NOEXPIRE_WITH_OPEN: May only be set when FH4_VOLATILE_ANY is + set. If this bit is set, then the meaning of FH4_VOLATILE_ANY + is qualified to exclude any expiration of the filehandle when it + is open. + + + + + +Haynes & Noveck Standards Track [Page 33] + +RFC 7530 NFSv4 March 2015 + + + FH4_VOL_MIGRATION: The filehandle will expire as a result of + migration. If FH4_VOLATILE_ANY is set, FH4_VOL_MIGRATION is + redundant. + + FH4_VOL_RENAME: The filehandle will expire during rename. This + includes a rename by the requesting client or a rename by any + other client. If FH4_VOLATILE_ANY is set, FH4_VOL_RENAME is + redundant. + + Servers that provide volatile filehandles that may expire while open + (i.e., if FH4_VOL_MIGRATION or FH4_VOL_RENAME is set or if + FH4_VOLATILE_ANY is set and FH4_NOEXPIRE_WITH_OPEN is not set) should + deny a RENAME or REMOVE that would affect an OPEN file of any of the + components leading to the OPEN file. In addition, the server SHOULD + deny all RENAME or REMOVE requests during the grace period upon + server restart. + + Note that the bits FH4_VOL_MIGRATION and FH4_VOL_RENAME allow the + client to determine that expiration has occurred whenever a specific + event occurs, without an explicit filehandle expiration error from + the server. FH4_VOLATILE_ANY does not provide this form of + information. In situations where the server will expire many, but + not all, filehandles upon migration (e.g., all but those that are + open), FH4_VOLATILE_ANY (in this case, with FH4_NOEXPIRE_WITH_OPEN) + is a better choice since the client may not assume that all + filehandles will expire when migration occurs, and it is likely that + additional expirations will occur (as a result of file CLOSE) that + are separated in time from the migration event itself. + +4.2.4. One Method of Constructing a Volatile Filehandle + + A volatile filehandle, while opaque to the client, could contain: + + [volatile bit = 1 | server boot time | slot | generation number] + + o slot is an index in the server volatile filehandle table + + o generation number is the generation number for the table + entry/slot + + When the client presents a volatile filehandle, the server makes the + following checks, which assume that the check for the volatile bit + has passed. If the server boot time is less than the current server + boot time, return NFS4ERR_FHEXPIRED. If slot is out of range, return + NFS4ERR_BADHANDLE. If the generation number does not match, return + NFS4ERR_FHEXPIRED. + + When the server reboots, the table is gone (it is volatile). + + + +Haynes & Noveck Standards Track [Page 34] + +RFC 7530 NFSv4 March 2015 + + + If the volatile bit is 0, then it is a persistent filehandle with a + different structure following it. + +4.3. Client Recovery from Filehandle Expiration + + If possible, the client should recover from the receipt of an + NFS4ERR_FHEXPIRED error. The client must take on additional + responsibility so that it may prepare itself to recover from the + expiration of a volatile filehandle. If the server returns + persistent filehandles, the client does not need these additional + steps. + + For volatile filehandles, most commonly the client will need to store + the component names leading up to and including the file system + object in question. With these names, the client should be able to + recover by finding a filehandle in the namespace that is still + available or by starting at the root of the server's file system + namespace. + + If the expired filehandle refers to an object that has been removed + from the file system, obviously the client will not be able to + recover from the expired filehandle. + + It is also possible that the expired filehandle refers to a file that + has been renamed. If the file was renamed by another client, again + it is possible that the original client will not be able to recover. + However, in the case that the client itself is renaming the file and + the file is open, it is possible that the client may be able to + recover. The client can determine the new pathname based on the + processing of the rename request. The client can then regenerate the + new filehandle based on the new pathname. The client could also use + the COMPOUND operation mechanism to construct a set of operations + like: + + RENAME A B + LOOKUP B + GETFH + + Note that the COMPOUND procedure does not provide atomicity. This + example only reduces the overhead of recovering from an expired + filehandle. + +5. Attributes + + To meet the requirements of extensibility and increased + interoperability with non-UNIX platforms, attributes need to be + handled in a flexible manner. The NFSv3 fattr3 structure contains a + fixed list of attributes that not all clients and servers are able to + + + +Haynes & Noveck Standards Track [Page 35] + +RFC 7530 NFSv4 March 2015 + + + support or care about. The fattr3 structure cannot be extended as + new needs arise, and it provides no way to indicate non-support. + With the NFSv4.0 protocol, the client is able to query what + attributes the server supports and construct requests with only those + supported attributes (or a subset thereof). + + To this end, attributes are divided into three groups: REQUIRED, + RECOMMENDED, and named. Both REQUIRED and RECOMMENDED attributes are + supported in the NFSv4.0 protocol by a specific and well-defined + encoding and are identified by number. They are requested by setting + a bit in the bit vector sent in the GETATTR request; the server + response includes a bit vector to list what attributes were returned + in the response. New REQUIRED or RECOMMENDED attributes may be added + to the NFSv4 protocol as part of a new minor version by publishing a + Standards Track RFC that allocates a new attribute number value and + defines the encoding for the attribute. See Section 11 for further + discussion. + + Named attributes are accessed by the OPENATTR operation, which + accesses a hidden directory of attributes associated with a file + system object. OPENATTR takes a filehandle for the object and + returns the filehandle for the attribute hierarchy. The filehandle + for the named attributes is a directory object accessible by LOOKUP + or READDIR and contains files whose names represent the named + attributes and whose data bytes are the value of the attribute. For + example: + + +----------+-----------+---------------------------------+ + | LOOKUP | "foo" | ; look up file | + | GETATTR | attrbits | | + | OPENATTR | | ; access foo's named attributes | + | LOOKUP | "x11icon" | ; look up specific attribute | + | READ | 0,4096 | ; read stream of bytes | + +----------+-----------+---------------------------------+ + + Named attributes are intended for data needed by applications rather + than by an NFS client implementation. NFS implementers are strongly + encouraged to define their new attributes as RECOMMENDED attributes + by bringing them to the IETF Standards Track process. + + The set of attributes that are classified as REQUIRED is deliberately + small since servers need to do whatever it takes to support them. A + server should support as many of the RECOMMENDED attributes as + possible; however, by their definition, the server is not required to + support all of them. Attributes are deemed REQUIRED if the data is + both needed by a large number of clients and is not otherwise + reasonably computable by the client when support is not provided on + the server. + + + +Haynes & Noveck Standards Track [Page 36] + +RFC 7530 NFSv4 March 2015 + + + Note that the hidden directory returned by OPENATTR is a convenience + for protocol processing. The client should not make any assumptions + about the server's implementation of named attributes and whether or + not the underlying file system at the server has a named attribute + directory. Therefore, operations such as SETATTR and GETATTR on the + named attribute directory are undefined. + +5.1. REQUIRED Attributes + + These attributes MUST be supported by every NFSv4.0 client and server + in order to ensure a minimum level of interoperability. The server + MUST store and return these attributes, and the client MUST be able + to function with an attribute set limited to these attributes. With + just the REQUIRED attributes, some client functionality can be + impaired or limited in some ways. A client can ask for any of these + attributes to be returned by setting a bit in the GETATTR request. + For each such bit set, the server MUST return the corresponding + attribute value. + +5.2. RECOMMENDED Attributes + + These attributes are understood well enough to warrant support in the + NFSv4.0 protocol. However, they may not be supported on all clients + and servers. A client MAY ask for any of these attributes to be + returned by setting a bit in the GETATTR request but MUST handle the + case where the server does not return them. A client MAY ask for the + set of attributes the server supports and SHOULD NOT request + attributes the server does not support. A server should be tolerant + of requests for unsupported attributes and simply not return them, + rather than considering the request an error. It is expected that + servers will support all attributes they comfortably can and only + fail to support attributes that are difficult to support in their + operating environments. A server should provide attributes whenever + they don't have to "tell lies" to the client. For example, a file + modification time either should be an accurate time or should not be + supported by the server. At times this will be difficult for + clients, but a client is better positioned to decide whether and how + to fabricate or construct an attribute or whether to do without the + attribute. + +5.3. Named Attributes + + These attributes are not supported by direct encoding in the NFSv4 + protocol but are accessed by string names rather than numbers and + correspond to an uninterpreted stream of bytes that are stored with + the file system object. The namespace for these attributes may be + accessed by using the OPENATTR operation. The OPENATTR operation + returns a filehandle for a virtual "named attribute directory", and + + + +Haynes & Noveck Standards Track [Page 37] + +RFC 7530 NFSv4 March 2015 + + + further perusal and modification of the namespace may be done using + operations that work on more typical directories. In particular, + READDIR may be used to get a list of such named attributes, and + LOOKUP and OPEN may select a particular attribute. Creation of a new + named attribute may be the result of an OPEN specifying file + creation. + + Once an OPEN is done, named attributes may be examined and changed by + normal READ and WRITE operations using the filehandles and stateids + returned by OPEN. + + Named attributes and the named attribute directory may have their own + (non-named) attributes. Each of these objects must have all of the + REQUIRED attributes and may have additional RECOMMENDED attributes. + However, the set of attributes for named attributes and the named + attribute directory need not be, and typically will not be, as large + as that for other objects in that file system. + + Named attributes might be the target of delegations. However, since + granting of delegations is at the server's discretion, a server need + not support delegations on named attributes. + + It is RECOMMENDED that servers support arbitrary named attributes. + A client should not depend on the ability to store any named + attributes in the server's file system. If a server does support + named attributes, a client that is also able to handle them should be + able to copy a file's data and metadata with complete transparency + from one location to another; this would imply that names allowed for + regular directory entries are valid for named attribute names + as well. + + In NFSv4.0, the structure of named attribute directories is + restricted in a number of ways, in order to prevent the development + of non-interoperable implementations in which some servers support a + fully general hierarchical directory structure for named attributes + while others support a limited but adequate structure for named + attributes. In such an environment, clients or applications might + come to depend on non-portable extensions. The restrictions are: + + o CREATE is not allowed in a named attribute directory. Thus, such + objects as symbolic links and special files are not allowed to be + named attributes. Further, directories may not be created in a + named attribute directory, so no hierarchical structure of named + attributes for a single object is allowed. + + o If OPENATTR is done on a named attribute directory or on a named + attribute, the server MUST return an error. + + + + +Haynes & Noveck Standards Track [Page 38] + +RFC 7530 NFSv4 March 2015 + + + o Doing a RENAME of a named attribute to a different named attribute + directory or to an ordinary (i.e., non-named-attribute) directory + is not allowed. + + o Creating hard links between named attribute directories or between + named attribute directories and ordinary directories is not + allowed. + + Names of attributes will not be controlled by this document or other + IETF Standards Track documents. See Section 20 for further + discussion. + +5.4. Classification of Attributes + + Each of the attributes accessed using SETATTR and GETATTR (i.e., + REQUIRED and RECOMMENDED attributes) can be classified in one of + three categories: + + 1. per-server attributes for which the value of the attribute will + be the same for all file objects that share the same server. + + 2. per-file system attributes for which the value of the attribute + will be the same for some or all file objects that share the same + server and fsid attribute (Section 5.8.1.9). See below for + details regarding when such sharing is in effect. + + 3. per-file system object attributes. + + The handling of per-file system attributes depends on the particular + attribute and the setting of the homogeneous (Section 5.8.2.12) + attribute. The following rules apply: + + 1. The values of the attributes supported_attrs, fsid, homogeneous, + link_support, and symlink_support are always common to all + objects within the given file system. + + 2. For other attributes, different values may be returned for + different file system objects if the attribute homogeneous is + supported within the file system in question and has the value + false. + + The classification of attributes is as follows. Note that the + attributes time_access_set and time_modify_set are not listed in this + section, because they are write-only attributes corresponding to + time_access and time_modify and are used in a special instance of + SETATTR. + + + + + +Haynes & Noveck Standards Track [Page 39] + +RFC 7530 NFSv4 March 2015 + + + o The per-server attribute is: + + lease_time + + o The per-file system attributes are: + + supported_attrs, fh_expire_type, link_support, symlink_support, + unique_handles, aclsupport, cansettime, case_insensitive, + case_preserving, chown_restricted, files_avail, files_free, + files_total, fs_locations, homogeneous, maxfilesize, maxname, + maxread, maxwrite, no_trunc, space_avail, space_free, + space_total, and time_delta + + o The per-file system object attributes are: + + type, change, size, named_attr, fsid, rdattr_error, filehandle, + acl, archive, fileid, hidden, maxlink, mimetype, mode, + numlinks, owner, owner_group, rawdev, space_used, system, + time_access, time_backup, time_create, time_metadata, + time_modify, and mounted_on_fileid + + For quota_avail_hard, quota_avail_soft, and quota_used, see their + definitions below for the appropriate classification. + +5.5. Set-Only and Get-Only Attributes + + Some REQUIRED and RECOMMENDED attributes are set-only; i.e., they can + be set via SETATTR but not retrieved via GETATTR. Similarly, some + REQUIRED and RECOMMENDED attributes are get-only; i.e., they can be + retrieved via GETATTR but not set via SETATTR. If a client attempts + to set a get-only attribute or get a set-only attribute, the server + MUST return NFS4ERR_INVAL. + +5.6. REQUIRED Attributes - List and Definition References + + The list of REQUIRED attributes appears in Table 3. The meanings of + the columns of the table are: + + o Name: The name of the attribute. + + o ID: The number assigned to the attribute. In the event of + conflicts between the assigned number and [RFC7531], the latter is + authoritative, but in such an event, it should be resolved with + errata to this document and/or [RFC7531]. See [IESG_ERRATA] for + the errata process. + + o Data Type: The XDR data type of the attribute. + + + + +Haynes & Noveck Standards Track [Page 40] + +RFC 7530 NFSv4 March 2015 + + + o Acc: Access allowed to the attribute. R means read-only (GETATTR + may retrieve, SETATTR may not set). W means write-only (SETATTR + may set, GETATTR may not retrieve). R W means read/write (GETATTR + may retrieve, SETATTR may set). + + o Defined in: The section of this specification that describes the + attribute. + + +-----------------+----+------------+-----+-------------------+ + | Name | ID | Data Type | Acc | Defined in | + +-----------------+----+------------+-----+-------------------+ + | supported_attrs | 0 | bitmap4 | R | Section 5.8.1.1 | + | type | 1 | nfs_ftype4 | R | Section 5.8.1.2 | + | fh_expire_type | 2 | uint32_t | R | Section 5.8.1.3 | + | change | 3 | changeid4 | R | Section 5.8.1.4 | + | size | 4 | uint64_t | R W | Section 5.8.1.5 | + | link_support | 5 | bool | R | Section 5.8.1.6 | + | symlink_support | 6 | bool | R | Section 5.8.1.7 | + | named_attr | 7 | bool | R | Section 5.8.1.8 | + | fsid | 8 | fsid4 | R | Section 5.8.1.9 | + | unique_handles | 9 | bool | R | Section 5.8.1.10 | + | lease_time | 10 | nfs_lease4 | R | Section 5.8.1.11 | + | rdattr_error | 11 | nfsstat4 | R | Section 5.8.1.12 | + | filehandle | 19 | nfs_fh4 | R | Section 5.8.1.13 | + +-----------------+----+------------+-----+-------------------+ + + Table 3: REQUIRED Attributes + +5.7. RECOMMENDED Attributes - List and Definition References + + The RECOMMENDED attributes are defined in Table 4. The meanings of + the column headers are the same as Table 3; see Section 5.6 for the + meanings. + + +-------------------+----+-----------------+-----+------------------+ + | Name | ID | Data Type | Acc | Defined in | + +-------------------+----+-----------------+-----+------------------+ + | acl | 12 | nfsace4<> | R W | Section 6.2.1 | + | aclsupport | 13 | uint32_t | R | Section 6.2.1.2 | + | archive | 14 | bool | R W | Section 5.8.2.1 | + | cansettime | 15 | bool | R | Section 5.8.2.2 | + | case_insensitive | 16 | bool | R | Section 5.8.2.3 | + | case_preserving | 17 | bool | R | Section 5.8.2.4 | + | chown_restricted | 18 | bool | R | Section 5.8.2.5 | + | fileid | 20 | uint64_t | R | Section 5.8.2.6 | + | files_avail | 21 | uint64_t | R | Section 5.8.2.7 | + | files_free | 22 | uint64_t | R | Section 5.8.2.8 | + | files_total | 23 | uint64_t | R | Section 5.8.2.9 | + + + +Haynes & Noveck Standards Track [Page 41] + +RFC 7530 NFSv4 March 2015 + + + | fs_locations | 24 | fs_locations4 | R | Section 5.8.2.10 | + | hidden | 25 | bool | R W | Section 5.8.2.11 | + | homogeneous | 26 | bool | R | Section 5.8.2.12 | + | maxfilesize | 27 | uint64_t | R | Section 5.8.2.13 | + | maxlink | 28 | uint32_t | R | Section 5.8.2.14 | + | maxname | 29 | uint32_t | R | Section 5.8.2.15 | + | maxread | 30 | uint64_t | R | Section 5.8.2.16 | + | maxwrite | 31 | uint64_t | R | Section 5.8.2.17 | + | mimetype | 32 | ascii_ | R W | Section 5.8.2.18 | + | | | REQUIRED4<> | | | + | mode | 33 | mode4 | R W | Section 6.2.2 | + | mounted_on_fileid | 55 | uint64_t | R | Section 5.8.2.19 | + | no_trunc | 34 | bool | R | Section 5.8.2.20 | + | numlinks | 35 | uint32_t | R | Section 5.8.2.21 | + | owner | 36 | utf8str_mixed | R W | Section 5.8.2.22 | + | owner_group | 37 | utf8str_mixed | R W | Section 5.8.2.23 | + | quota_avail_hard | 38 | uint64_t | R | Section 5.8.2.24 | + | quota_avail_soft | 39 | uint64_t | R | Section 5.8.2.25 | + | quota_used | 40 | uint64_t | R | Section 5.8.2.26 | + | rawdev | 41 | specdata4 | R | Section 5.8.2.27 | + | space_avail | 42 | uint64_t | R | Section 5.8.2.28 | + | space_free | 43 | uint64_t | R | Section 5.8.2.29 | + | space_total | 44 | uint64_t | R | Section 5.8.2.30 | + | space_used | 45 | uint64_t | R | Section 5.8.2.31 | + | system | 46 | bool | R W | Section 5.8.2.32 | + | time_access | 47 | nfstime4 | R | Section 5.8.2.33 | + | time_access_set | 48 | settime4 | W | Section 5.8.2.34 | + | time_backup | 49 | nfstime4 | R W | Section 5.8.2.35 | + | time_create | 50 | nfstime4 | R W | Section 5.8.2.36 | + | time_delta | 51 | nfstime4 | R | Section 5.8.2.37 | + | time_metadata | 52 | nfstime4 | R | Section 5.8.2.38 | + | time_modify | 53 | nfstime4 | R | Section 5.8.2.39 | + | time_modify_set | 54 | settime4 | W | Section 5.8.2.40 | + +-------------------+----+-----------------+-----+------------------+ + + Table 4: RECOMMENDED Attributes + +5.8. Attribute Definitions + +5.8.1. Definitions of REQUIRED Attributes + +5.8.1.1. Attribute 0: supported_attrs + + The bit vector that would retrieve all REQUIRED and RECOMMENDED + attributes that are supported for this object. The scope of this + attribute applies to all objects with a matching fsid. + + + + + +Haynes & Noveck Standards Track [Page 42] + +RFC 7530 NFSv4 March 2015 + + +5.8.1.2. Attribute 1: type + + Designates the type of an object in terms of one of a number of + special constants: + + o NF4REG designates a regular file. + + o NF4DIR designates a directory. + + o NF4BLK designates a block device special file. + + o NF4CHR designates a character device special file. + + o NF4LNK designates a symbolic link. + + o NF4SOCK designates a named socket special file. + + o NF4FIFO designates a fifo special file. + + o NF4ATTRDIR designates a named attribute directory. + + o NF4NAMEDATTR designates a named attribute. + + Within the explanatory text and operation descriptions, the following + phrases will be used with the meanings given below: + + o The phrase "is a directory" means that the object's type attribute + is NF4DIR or NF4ATTRDIR. + + o The phrase "is a special file" means that the object's type + attribute is NF4BLK, NF4CHR, NF4SOCK, or NF4FIFO. + + o The phrase "is a regular file" means that the object's type + attribute is NF4REG or NF4NAMEDATTR. + + o The phrase "is a symbolic link" means that the object's type + attribute is NF4LNK. + +5.8.1.3. Attribute 2: fh_expire_type + + The server uses this to specify filehandle expiration behavior to the + client. See Section 4 for additional description. + + + + + + + + + +Haynes & Noveck Standards Track [Page 43] + +RFC 7530 NFSv4 March 2015 + + +5.8.1.4. Attribute 3: change + + A value created by the server that the client can use to determine if + file data, directory contents, or attributes of the object have been + modified. The server MAY return the object's time_metadata attribute + for this attribute's value but only if the file system object cannot + be updated more frequently than the resolution of time_metadata. + +5.8.1.5. Attribute 4: size + + The size of the object in bytes. + +5.8.1.6. Attribute 5: link_support + + TRUE, if the object's file system supports hard links. + +5.8.1.7. Attribute 6: symlink_support + + TRUE, if the object's file system supports symbolic links. + +5.8.1.8. Attribute 7: named_attr + + TRUE, if this object has named attributes. In other words, this + object has a non-empty named attribute directory. + +5.8.1.9. Attribute 8: fsid + + Unique file system identifier for the file system holding this + object. The fsid attribute has major and minor components, each of + which are of data type uint64_t. + +5.8.1.10. Attribute 9: unique_handles + + TRUE, if two distinct filehandles are guaranteed to refer to two + different file system objects. + +5.8.1.11. Attribute 10: lease_time + + Duration of the lease at the server in seconds. + +5.8.1.12. Attribute 11: rdattr_error + + Error returned from an attempt to retrieve attributes during a + READDIR operation. + +5.8.1.13. Attribute 19: filehandle + + The filehandle of this object (primarily for READDIR requests). + + + +Haynes & Noveck Standards Track [Page 44] + +RFC 7530 NFSv4 March 2015 + + +5.8.2. Definitions of Uncategorized RECOMMENDED Attributes + + The definitions of most of the RECOMMENDED attributes follow. + Collections that share a common category are defined in other + sections. + +5.8.2.1. Attribute 14: archive + + TRUE, if this file has been archived since the time of the last + modification (deprecated in favor of time_backup). + +5.8.2.2. Attribute 15: cansettime + + TRUE, if the server is able to change the times for a file system + object as specified in a SETATTR operation. + +5.8.2.3. Attribute 16: case_insensitive + + TRUE, if filename comparisons on this file system are case + insensitive. This refers only to comparisons, and not to the case in + which filenames are stored. + +5.8.2.4. Attribute 17: case_preserving + + TRUE, if the filename case on this file system is preserved. This + refers only to how filenames are stored, and not to how they are + compared. Filenames stored in mixed case might be compared using + either case-insensitive or case-sensitive comparisons. + +5.8.2.5. Attribute 18: chown_restricted + + If TRUE, the server will reject any request to change either the + owner or the group associated with a file if the caller is not a + privileged user (for example, "root" in UNIX operating environments + or the "Take Ownership" privilege in Windows 2000). + +5.8.2.6. Attribute 20: fileid + + A number uniquely identifying the file within the file system. + +5.8.2.7. Attribute 21: files_avail + + File slots available to this user on the file system containing this + object -- this should be the smallest relevant limit. + + + + + + + +Haynes & Noveck Standards Track [Page 45] + +RFC 7530 NFSv4 March 2015 + + +5.8.2.8. Attribute 22: files_free + + Free file slots on the file system containing this object -- this + should be the smallest relevant limit. + +5.8.2.9. Attribute 23: files_total + + Total file slots on the file system containing this object. + +5.8.2.10. Attribute 24: fs_locations + + Locations where this file system may be found. If the server returns + NFS4ERR_MOVED as an error, this attribute MUST be supported. + + The server specifies the rootpath for a given server by returning a + path consisting of zero path components. + +5.8.2.11. Attribute 25: hidden + + TRUE, if the file is considered hidden with respect to the + Windows API. + +5.8.2.12. Attribute 26: homogeneous + + TRUE, if this object's file system is homogeneous, i.e., all objects + in the file system (all objects on the server with the same fsid) + have common values for all per-file system attributes. + +5.8.2.13. Attribute 27: maxfilesize + + Maximum supported file size for the file system of this object. + +5.8.2.14. Attribute 28: maxlink + + Maximum number of hard links for this object. + +5.8.2.15. Attribute 29: maxname + + Maximum filename size supported for this object. + +5.8.2.16. Attribute 30: maxread + + Maximum amount of data the READ operation will return for this + object. + + + + + + + +Haynes & Noveck Standards Track [Page 46] + +RFC 7530 NFSv4 March 2015 + + +5.8.2.17. Attribute 31: maxwrite + + Maximum amount of data the WRITE operation will accept for this + object. This attribute SHOULD be supported if the file is writable. + Lack of this attribute can lead to the client either wasting + bandwidth or not receiving the best performance. + +5.8.2.18. Attribute 32: mimetype + + MIME media type/subtype of this object. + +5.8.2.19. Attribute 55: mounted_on_fileid + + Like fileid, but if the target filehandle is the root of a file + system, this attribute represents the fileid of the underlying + directory. + + UNIX-based operating environments connect a file system into the + namespace by connecting (mounting) the file system onto the existing + file object (the mount point, usually a directory) of an existing + file system. When the mount point's parent directory is read via an + API such as readdir() [readdir_api], the return results are directory + entries, each with a component name and a fileid. The fileid of the + mount point's directory entry will be different from the fileid that + the stat() [stat] system call returns. The stat() system call is + returning the fileid of the root of the mounted file system, whereas + readdir() is returning the fileid that stat() would have returned + before any file systems were mounted on the mount point. + + Unlike NFSv3, NFSv4.0 allows a client's LOOKUP request to cross other + file systems. The client detects the file system crossing whenever + the filehandle argument of LOOKUP has an fsid attribute different + from that of the filehandle returned by LOOKUP. A UNIX-based client + will consider this a "mount point crossing". UNIX has a legacy + scheme for allowing a process to determine its current working + directory. This relies on readdir() of a mount point's parent and + stat() of the mount point returning fileids as previously described. + The mounted_on_fileid attribute corresponds to the fileid that + readdir() would have returned, as described previously. + + While the NFSv4.0 client could simply fabricate a fileid + corresponding to what mounted_on_fileid provides (and if the server + does not support mounted_on_fileid, the client has no choice), there + is a risk that the client will generate a fileid that conflicts with + one that is already assigned to another object in the file system. + Instead, if the server can provide the mounted_on_fileid, the + potential for client operational problems in this area is eliminated. + + + + +Haynes & Noveck Standards Track [Page 47] + +RFC 7530 NFSv4 March 2015 + + + If the server detects that there is nothing mounted on top of the + target file object, then the value for mounted_on_fileid that it + returns is the same as that of the fileid attribute. + + The mounted_on_fileid attribute is RECOMMENDED, so the server SHOULD + provide it if possible, and for a UNIX-based server, this is + straightforward. Usually, mounted_on_fileid will be requested during + a READDIR operation, in which case it is trivial (at least for + UNIX-based servers) to return mounted_on_fileid since it is equal to + the fileid of a directory entry returned by readdir(). If + mounted_on_fileid is requested in a GETATTR operation, the server + should obey an invariant that has it returning a value that is equal + to the file object's entry in the object's parent directory, i.e., + what readdir() would have returned. Some operating environments + allow a series of two or more file systems to be mounted onto a + single mount point. In this case, for the server to obey the + aforementioned invariant, it will need to find the base mount point, + and not the intermediate mount points. + +5.8.2.20. Attribute 34: no_trunc + + If this attribute is TRUE, then if the client uses a filename longer + than name_max, an error will be returned instead of the name being + truncated. + +5.8.2.21. Attribute 35: numlinks + + Number of hard links to this object. + +5.8.2.22. Attribute 36: owner + + The string name of the owner of this object. + +5.8.2.23. Attribute 37: owner_group + + The string name of the group ownership of this object. + +5.8.2.24. Attribute 38: quota_avail_hard + + The value in bytes that represents the amount of additional disk + space beyond the current allocation that can be allocated to this + file or directory before further allocations will be refused. It is + understood that this space may be consumed by allocations to other + files or directories. + + + + + + + +Haynes & Noveck Standards Track [Page 48] + +RFC 7530 NFSv4 March 2015 + + +5.8.2.25. Attribute 39: quota_avail_soft + + The value in bytes that represents the amount of additional disk + space that can be allocated to this file or directory before the user + may reasonably be warned. It is understood that this space may be + consumed by allocations to other files or directories, though there + may exist server-side rules as to which other files or directories. + +5.8.2.26. Attribute 40: quota_used + + The value in bytes that represents the amount of disk space used by + this file or directory and possibly a number of other similar files + or directories, where the set of "similar" meets at least the + criterion that allocating space to any file or directory in the set + will reduce the "quota_avail_hard" of every other file or directory + in the set. + + Note that there may be a number of distinct but overlapping sets of + files or directories for which a quota_used value is maintained, + e.g., "all files with a given owner", "all files with a given group + owner", etc. The server is at liberty to choose any of those sets + when providing the content of the quota_used attribute but should do + so in a repeatable way. The rule may be configured per file system + or may be "choose the set with the smallest quota". + +5.8.2.27. Attribute 41: rawdev + + Raw device number of file of type NF4BLK or NF4CHR. The device + number is split into major and minor numbers. If the file's type + attribute is not NF4BLK or NF4CHR, this attribute SHOULD NOT be + returned, and any value returned SHOULD NOT be considered useful. + +5.8.2.28. Attribute 42: space_avail + + Disk space in bytes available to this user on the file system + containing this object -- this should be the smallest relevant limit. + +5.8.2.29. Attribute 43: space_free + + Free disk space in bytes on the file system containing this object -- + this should be the smallest relevant limit. + +5.8.2.30. Attribute 44: space_total + + Total disk space in bytes on the file system containing this object. + + + + + + +Haynes & Noveck Standards Track [Page 49] + +RFC 7530 NFSv4 March 2015 + + +5.8.2.31. Attribute 45: space_used + + Number of file system bytes allocated to this object. + +5.8.2.32. Attribute 46: system + + TRUE, if this file is a "system" file with respect to the Windows + operating environment. + +5.8.2.33. Attribute 47: time_access + + Represents the time of last access to the object by a READ operation + sent to the server. The notion of what is an "access" depends on the + server's operating environment and/or the server's file system + semantics. For example, for servers obeying Portable Operating + System Interface (POSIX) semantics, time_access would be updated only + by the READ and READDIR operations and not any of the operations that + modify the content of the object [read_api], [readdir_api], + [write_api]. Of course, setting the corresponding time_access_set + attribute is another way to modify the time_access attribute. + + Whenever the file object resides on a writable file system, the + server should make its best efforts to record time_access into stable + storage. However, to mitigate the performance effects of doing so, + and most especially whenever the server is satisfying the read of the + object's content from its cache, the server MAY cache access time + updates and lazily write them to stable storage. It is also + acceptable to give administrators of the server the option to disable + time_access updates. + +5.8.2.34. Attribute 48: time_access_set + + Sets the time of last access to the object. SETATTR use only. + +5.8.2.35. Attribute 49: time_backup + + The time of last backup of the object. + +5.8.2.36. Attribute 50: time_create + + The time of creation of the object. This attribute does not have + any relation to the traditional UNIX file attribute "ctime" + ("change time"). + +5.8.2.37. Attribute 51: time_delta + + Smallest useful server time granularity. + + + + +Haynes & Noveck Standards Track [Page 50] + +RFC 7530 NFSv4 March 2015 + + +5.8.2.38. Attribute 52: time_metadata + + The time of last metadata modification of the object. + +5.8.2.39. Attribute 53: time_modify + + The time of last modification to the object. + +5.8.2.40. Attribute 54: time_modify_set + + Sets the time of last modification to the object. SETATTR use only. + +5.9. Interpreting owner and owner_group + + The RECOMMENDED attributes "owner" and "owner_group" (and also users + and groups used as values of the who field within nfs4ace structures + used in the acl attribute) are represented in the form of UTF-8 + strings. This format avoids the use of a representation that is tied + to a particular underlying implementation at the client or server. + Note that Section 6.1 of [RFC2624] provides additional rationale. It + is expected that the client and server will have their own local + representation of owners and groups that is used for local storage or + presentation to the application via APIs that expect such a + representation. Therefore, the protocol requires that when these + attributes are transferred between the client and server, the local + representation is translated to a string of the form + "identifier@dns_domain". This allows clients and servers that do not + use the same local representation to effectively interoperate since + they both use a common syntax that can be interpreted by both. + + Similarly, security principals may be represented in different ways + by different security mechanisms. Servers normally translate these + representations into a common format, generally that used by local + storage, to serve as a means of identifying the users corresponding + to these security principals. When these local identifiers are + translated to the form of the owner attribute, associated with files + created by such principals, they identify, in a common format, the + users associated with each corresponding set of security principals. + + The translation used to interpret owner and group strings is not + specified as part of the protocol. This allows various solutions to + be employed. For example, a local translation table may be consulted + that maps a numeric identifier to the user@dns_domain syntax. A name + service may also be used to accomplish the translation. A server may + provide a more general service, not limited by any particular + translation (which would only translate a limited set of possible + strings) by storing the owner and owner_group attributes in local + storage without any translation, or it may augment a translation + + + +Haynes & Noveck Standards Track [Page 51] + +RFC 7530 NFSv4 March 2015 + + + method by storing the entire string for attributes for which no + translation is available while using the local representation for + those cases in which a translation is available. + + Servers that do not provide support for all possible values of user + and group strings SHOULD return an error (NFS4ERR_BADOWNER) when a + string is presented that has no translation, as the value to be set + for a SETATTR of the owner or owner_group attributes or as part of + the value of the acl attribute. When a server does accept a user or + group string as valid on a SETATTR, it is promising to return that + same string (see below) when a corresponding GETATTR is done, as long + as there has been no further change in the corresponding attribute + before the GETATTR. For some internationalization-related exceptions + where this is not possible, see below. Configuration changes + (including changes from the mapping of the string to the local + representation) and ill-constructed name translations (those that + contain aliasing) may make that promise impossible to honor. Servers + should make appropriate efforts to avoid a situation in which these + attributes have their values changed when no real change to either + ownership or acls has occurred. + + The "dns_domain" portion of the owner string is meant to be a DNS + domain name -- for example, "user@example.org". Servers should + accept as valid a set of users for at least one domain. A server may + treat other domains as having no valid translations. A more general + service is provided when a server is capable of accepting users for + multiple domains, or for all domains, subject to security + constraints. + + As an implementation guide, both clients and servers may provide a + means to configure the "dns_domain" portion of the owner string. For + example, the DNS domain name of the host running the NFS server might + be "lab.example.org", but the user names are defined in + "example.org". In the absence of such a configuration, or as a + default, the current DNS domain name of the server should be the + value used for the "dns_domain". + + As mentioned above, it is desirable that a server, when accepting a + string of the form "user@domain" or "group@domain" in an attribute, + return this same string when that corresponding attribute is fetched. + Internationalization issues make this impossible under certain + circumstances, and the client needs to take note of these. See + Section 12 for a detailed discussion of these issues. + + In the case where there is no translation available to the client or + server, the attribute value will be constructed without the "@". + Therefore, the absence of the "@" from the owner or owner_group + attribute signifies that no translation was available at the sender + + + +Haynes & Noveck Standards Track [Page 52] + +RFC 7530 NFSv4 March 2015 + + + and that the receiver of the attribute should not use that string as + a basis for translation into its own internal format. Even though + the attribute value cannot be translated, it may still be useful. In + the case of a client, the attribute string may be used for local + display of ownership. + + To provide a greater degree of compatibility with NFSv3, which + identified users and groups by 32-bit unsigned user identifiers and + group identifiers, owner and group strings that consist of ASCII- + encoded decimal numeric values with no leading zeros can be given a + special interpretation by clients and servers that choose to provide + such support. The receiver may treat such a user or group string as + representing the same user as would be represented by an NFSv3 uid or + gid having the corresponding numeric value. + + A server SHOULD reject such a numeric value if the security mechanism + is using Kerberos. That is, in such a scenario, the client will + already need to form "user@domain" strings. For any other security + mechanism, the server SHOULD accept such numeric values. As an + implementation note, the server could make such an acceptance be + configurable. If the server does not support numeric values or if it + is configured off, then it MUST return an NFS4ERR_BADOWNER error. If + the security mechanism is using Kerberos and the client attempts to + use the special form, then the server SHOULD return an + NFS4ERR_BADOWNER error when there is a valid translation for the user + or owner designated in this way. In that case, the client must use + the appropriate user@domain string and not the special form for + compatibility. + + The client MUST always accept numeric values if the security + mechanism is not RPCSEC_GSS. A client can determine if a server + supports numeric identifiers by first attempting to provide a numeric + identifier. If this attempt is rejected with an NFS4ERR_BADOWNER + error, then the client should only use named identifiers of the form + "user@dns_domain". + + The owner string "nobody" may be used to designate an anonymous user, + which will be associated with a file created by a security principal + that cannot be mapped through normal means to the owner attribute. + +5.10. Character Case Attributes + + With respect to the case_insensitive and case_preserving attributes, + case-insensitive comparisons of Unicode characters SHOULD use Unicode + Default Case Folding as defined in Chapter 3 of the Unicode Standard + [UNICODE] and MAY override that behavior for specific selected + characters with the case folding defined in the SpecialCasing.txt + [SPECIALCASING] file; see Section 3.13 of the Unicode Standard. + + + +Haynes & Noveck Standards Track [Page 53] + +RFC 7530 NFSv4 March 2015 + + + The SpecialCasing.txt file replaces the Default Case Folding with + locale- and context-dependent case folding for specific situations. + An example of locale- and context-dependent case folding is that + LATIN CAPITAL LETTER I ("I", U+0049) is default case folded to LATIN + SMALL LETTER I ("i", U+0069). However, several languages (e.g., + Turkish) treat an "I" character with a dot as a different letter than + an "I" character without a dot; therefore, in such languages, unless + an I is before a dot_above, the "I" (U+0049) character should be case + folded to a different character, LATIN SMALL LETTER DOTLESS I + (U+0131). + + The [UNICODE] and [SPECIALCASING] references in this RFC are for + version 7.0.0 of the Unicode standard, as that was the latest version + of Unicode when this RFC was published. Implementations SHOULD + always use the latest version of Unicode + (). + +6. Access Control Attributes + + Access Control Lists (ACLs) are file attributes that specify fine- + grained access control. This section covers the "acl", "aclsupport", + and "mode" file attributes, and their interactions. Note that file + attributes may apply to any file system object. + +6.1. Goals + + ACLs and modes represent two well-established models for specifying + permissions. This section specifies requirements that attempt to + meet the following goals: + + o If a server supports the mode attribute, it should provide + reasonable semantics to clients that only set and retrieve the + mode attribute. + + o If a server supports ACL attributes, it should provide reasonable + semantics to clients that only set and retrieve those attributes. + + o On servers that support the mode attribute, if ACL attributes have + never been set on an object, via inheritance or explicitly, the + behavior should be traditional UNIX-like behavior. + + o On servers that support the mode attribute, if the ACL attributes + have been previously set on an object, either explicitly or via + inheritance: + + * Setting only the mode attribute should effectively control the + traditional UNIX-like permissions of read, write, and execute + on owner, owner_group, and other. + + + +Haynes & Noveck Standards Track [Page 54] + +RFC 7530 NFSv4 March 2015 + + + * Setting only the mode attribute should provide reasonable + security. For example, setting a mode of 000 should be enough + to ensure that future opens for read or write by any principal + fail, regardless of a previously existing or inherited ACL. + + o When a mode attribute is set on an object, the ACL attributes may + need to be modified so as to not conflict with the new mode. In + such cases, it is desirable that the ACL keep as much information + as possible. This includes information about inheritance, AUDIT + and ALARM access control entries (ACEs), and permissions granted + and denied that do not conflict with the new mode. + +6.2. File Attributes Discussion + + Support for each of the ACL attributes is RECOMMENDED and not + required, since file systems accessed using NFSv4 might not + support ACLs. + +6.2.1. Attribute 12: acl + + The NFSv4.0 ACL attribute contains an array of ACEs that are + associated with the file system object. Although the client can read + and write the acl attribute, the server is responsible for using the + ACL to perform access control. The client can use the OPEN or ACCESS + operations to check access without modifying or reading data or + metadata. + + The NFS ACE structure is defined as follows: + + typedef uint32_t acetype4; + + typedef uint32_t aceflag4; + + typedef uint32_t acemask4; + + struct nfsace4 { + acetype4 type; + aceflag4 flag; + acemask4 access_mask; + utf8str_mixed who; + }; + + To determine if a request succeeds, the server processes each nfsace4 + entry in order. Only ACEs that have a "who" that matches 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 + 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 + + + +Haynes & Noveck Standards Track [Page 55] + +RFC 7530 NFSv4 March 2015 + + + is encountered where the requester's access still has unALLOWED bits + 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 + mask that have not been ALLOWED or DENIED, access is denied. + + Unlike the ALLOW and DENY ACE types, the ALARM and AUDIT ACE types do + not affect a requester's access and instead are for triggering events + as a result of a requester's access attempt. Therefore, AUDIT and + ALARM ACEs are processed only after processing ALLOW and DENY ACEs. + + The NFSv4.0 ACL model is quite rich. Some server platforms may + provide access control functionality that goes beyond the UNIX-style + mode attribute but that is not as rich as the NFS ACL model. So that + users can take advantage of this more limited functionality, the + server may support the acl attributes by mapping between its ACL + model and the NFSv4.0 ACL model. Servers must ensure that the ACL + they actually store or enforce is at least as strict as the NFSv4 ACL + that was set. It is tempting to accomplish this by rejecting any ACL + that falls outside the small set that can be represented accurately. + However, such an approach can render ACLs unusable without special + client-side knowledge of the server's mapping, which defeats the + purpose of having a common NFSv4 ACL protocol. Therefore, servers + should accept every ACL that they can without compromising security. + To help accomplish this, servers may make a special exception, in the + case of unsupported permission bits, to the rule that bits not + ALLOWED or DENIED by an ACL must be denied. For example, a UNIX- + style server might choose to silently allow read attribute + permissions even though an ACL does not explicitly allow those + permissions. (An ACL that explicitly denies permission to read + attributes should still result in a denial.) + + The situation is complicated by the fact that a server may have + multiple modules that enforce ACLs. For example, the enforcement for + NFSv4.0 access may be different from, but not weaker than, the + enforcement for local access, and both may be different from the + enforcement for access through other protocols such as Server Message + Block (SMB) [MS-SMB]. So it may be useful for a server to accept an + ACL even if not all of its modules are able to support it. + + The guiding principle with regard to NFSv4 access is that the server + must not accept ACLs that give an appearance of more restricted + access to a file than what is actually enforced. + + + + + + + + + +Haynes & Noveck Standards Track [Page 56] + +RFC 7530 NFSv4 March 2015 + + +6.2.1.1. ACE Type + + The constants used for the type field (acetype4) are as follows: + + const ACE4_ACCESS_ALLOWED_ACE_TYPE = 0x00000000; + const ACE4_ACCESS_DENIED_ACE_TYPE = 0x00000001; + const ACE4_SYSTEM_AUDIT_ACE_TYPE = 0x00000002; + const ACE4_SYSTEM_ALARM_ACE_TYPE = 0x00000003; + + All four bit types are permitted in the acl attribute. + + +------------------------------+--------------+---------------------+ + | Value | Abbreviation | Description | + +------------------------------+--------------+---------------------+ + | ACE4_ACCESS_ALLOWED_ACE_TYPE | ALLOW | Explicitly grants | + | | | the access defined | + | | | in acemask4 to the | + | | | file or directory. | + | | | | + | ACE4_ACCESS_DENIED_ACE_TYPE | DENY | Explicitly denies | + | | | the access defined | + | | | in acemask4 to the | + | | | file or directory. | + | | | | + | ACE4_SYSTEM_AUDIT_ACE_TYPE | AUDIT | LOG (in a system- | + | | | dependent way) any | + | | | access attempt to a | + | | | file or directory | + | | | that uses any of | + | | | the access methods | + | | | specified in | + | | | acemask4. | + | | | | + | ACE4_SYSTEM_ALARM_ACE_TYPE | ALARM | Generate a system | + | | | ALARM (system | + | | | dependent) when any | + | | | access attempt is | + | | | made to a file or | + | | | directory for the | + | | | access methods | + | | | specified in | + | | | acemask4. | + +------------------------------+--------------+---------------------+ + + The "Abbreviation" column denotes how the types will be referred to + throughout the rest of this section. + + + + + +Haynes & Noveck Standards Track [Page 57] + +RFC 7530 NFSv4 March 2015 + + +6.2.1.2. Attribute 13: aclsupport + + A server need not support all of the above ACE types. This attribute + indicates which ACE types are supported for the current file system. + The bitmask constants used to represent the above definitions within + the aclsupport attribute are as follows: + + const ACL4_SUPPORT_ALLOW_ACL = 0x00000001; + const ACL4_SUPPORT_DENY_ACL = 0x00000002; + const ACL4_SUPPORT_AUDIT_ACL = 0x00000004; + const ACL4_SUPPORT_ALARM_ACL = 0x00000008; + + Servers that support either the ALLOW or DENY ACE type SHOULD support + both ALLOW and DENY ACE types. + + Clients should not attempt to set an ACE unless the server claims + support for that ACE type. If the server receives a request to set + an ACE that it cannot store, it MUST reject the request with + NFS4ERR_ATTRNOTSUPP. If the server receives a request to set an ACE + that it can store but cannot enforce, the server SHOULD reject the + request with NFS4ERR_ATTRNOTSUPP. + +6.2.1.3. ACE Access Mask + + The bitmask constants used for the access mask field are as follows: + + const ACE4_READ_DATA = 0x00000001; + const ACE4_LIST_DIRECTORY = 0x00000001; + const ACE4_WRITE_DATA = 0x00000002; + const ACE4_ADD_FILE = 0x00000002; + const ACE4_APPEND_DATA = 0x00000004; + const ACE4_ADD_SUBDIRECTORY = 0x00000004; + const ACE4_READ_NAMED_ATTRS = 0x00000008; + const ACE4_WRITE_NAMED_ATTRS = 0x00000010; + const ACE4_EXECUTE = 0x00000020; + const ACE4_DELETE_CHILD = 0x00000040; + const ACE4_READ_ATTRIBUTES = 0x00000080; + const ACE4_WRITE_ATTRIBUTES = 0x00000100; + + const ACE4_DELETE = 0x00010000; + const ACE4_READ_ACL = 0x00020000; + const ACE4_WRITE_ACL = 0x00040000; + const ACE4_WRITE_OWNER = 0x00080000; + const ACE4_SYNCHRONIZE = 0x00100000; + + + + + + + +Haynes & Noveck Standards Track [Page 58] + +RFC 7530 NFSv4 March 2015 + + + Note that some masks have coincident values -- for example, + ACE4_READ_DATA and ACE4_LIST_DIRECTORY. The mask entries + ACE4_LIST_DIRECTORY, ACE4_ADD_FILE, and ACE4_ADD_SUBDIRECTORY are + intended to be used with directory objects, while ACE4_READ_DATA, + ACE4_WRITE_DATA, and ACE4_APPEND_DATA are intended to be used with + non-directory objects. + +6.2.1.3.1. Discussion of Mask Attributes + + ACE4_READ_DATA + + Operation(s) affected: + + READ + + OPEN + + Discussion: + + Permission to read the data of the file. + + Servers SHOULD allow a user the ability to read the data of the + file when only the ACE4_EXECUTE access mask bit is set. + + ACE4_LIST_DIRECTORY + + Operation(s) affected: + + READDIR + + Discussion: + + Permission to list the contents of a directory. + + ACE4_WRITE_DATA + + Operation(s) affected: + + WRITE + + OPEN + + SETATTR of size + + Discussion: + + Permission to modify a file's data. + + + + +Haynes & Noveck Standards Track [Page 59] + +RFC 7530 NFSv4 March 2015 + + + ACE4_ADD_FILE + + Operation(s) affected: + + CREATE + + LINK + + OPEN + + RENAME + + Discussion: + + Permission to add a new file in a directory. The CREATE + operation is affected when nfs_ftype4 is NF4LNK, NF4BLK, + NF4CHR, NF4SOCK, or NF4FIFO. (NF4DIR is not listed because it + is covered by ACE4_ADD_SUBDIRECTORY.) OPEN is affected when + used to create a regular file. LINK and RENAME are always + affected. + + ACE4_APPEND_DATA + + Operation(s) affected: + + WRITE + + OPEN + + SETATTR of size + + Discussion: + + The ability to modify a file's data, but only starting at EOF. + This allows for the notion of append-only files, by allowing + ACE4_APPEND_DATA and denying ACE4_WRITE_DATA to the same user + or group. If a file has an ACL such as the one described above + and a WRITE request is made for somewhere other than EOF, the + server SHOULD return NFS4ERR_ACCESS. + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 60] + +RFC 7530 NFSv4 March 2015 + + + ACE4_ADD_SUBDIRECTORY + + Operation(s) affected: + + CREATE + + RENAME + + Discussion: + + Permission to create a subdirectory in a directory. The CREATE + operation is affected when nfs_ftype4 is NF4DIR. The RENAME + operation is always affected. + + ACE4_READ_NAMED_ATTRS + + Operation(s) affected: + + OPENATTR + + Discussion: + + Permission to read the named attributes of a file or to look up + the named attributes directory. OPENATTR is affected when it + is not used to create a named attribute directory. This is + when 1) createdir is TRUE but a named attribute directory + already exists or 2) createdir is FALSE. + + ACE4_WRITE_NAMED_ATTRS + + Operation(s) affected: + + OPENATTR + + Discussion: + + Permission to write the named attributes of a file or to create + a named attribute directory. OPENATTR is affected when it is + used to create a named attribute directory. This is when + createdir is TRUE and no named attribute directory exists. The + ability to check whether or not a named attribute directory + exists depends on the ability to look it up; therefore, users + also need the ACE4_READ_NAMED_ATTRS permission in order to + create a named attribute directory. + + + + + + + +Haynes & Noveck Standards Track [Page 61] + +RFC 7530 NFSv4 March 2015 + + + ACE4_EXECUTE + + Operation(s) affected: + + READ + + Discussion: + + Permission to execute a file. + + Servers SHOULD allow a user the ability to read the data of the + file when only the ACE4_EXECUTE access mask bit is set. This + is because there is no way to execute a file without reading + the contents. Though a server may treat ACE4_EXECUTE and + ACE4_READ_DATA bits identically when deciding to permit a READ + operation, it SHOULD still allow the two bits to be set + independently in ACLs and MUST distinguish between them when + replying to ACCESS operations. In particular, servers SHOULD + NOT silently turn on one of the two bits when the other is set, + as that would make it impossible for the client to correctly + enforce the distinction between read and execute permissions. + + As an example, following a SETATTR of the following ACL: + + nfsuser:ACE4_EXECUTE:ALLOW + + A subsequent GETATTR of ACL for that file SHOULD return: + + nfsuser:ACE4_EXECUTE:ALLOW + + Rather than: + + nfsuser:ACE4_EXECUTE/ACE4_READ_DATA:ALLOW + + + + + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 62] + +RFC 7530 NFSv4 March 2015 + + + ACE4_EXECUTE + + Operation(s) affected: + + LOOKUP + + OPEN + + REMOVE + + RENAME + + LINK + + CREATE + + Discussion: + + Permission to traverse/search a directory. + + ACE4_DELETE_CHILD + + Operation(s) affected: + + REMOVE + + RENAME + + Discussion: + + Permission to delete a file or directory within a directory. + See Section 6.2.1.3.2 for information on how ACE4_DELETE and + ACE4_DELETE_CHILD interact. + + + + + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 63] + +RFC 7530 NFSv4 March 2015 + + + ACE4_READ_ATTRIBUTES + + Operation(s) affected: + + GETATTR of file system object attributes + + VERIFY + + NVERIFY + + READDIR + + Discussion: + + The ability to read basic attributes (non-ACLs) of a file. + On a UNIX system, basic attributes can be thought of as the + stat-level attributes. Allowing this access mask bit would + mean the entity can execute "ls -l" and stat. If a READDIR + operation requests attributes, this mask must be allowed for + the READDIR to succeed. + + ACE4_WRITE_ATTRIBUTES + + Operation(s) affected: + + SETATTR of time_access_set, time_backup, time_create, + time_modify_set, mimetype, hidden, and system + + Discussion: + + Permission to change the times associated with a file or + directory to an arbitrary value. Also, permission to change + the mimetype, hidden and system attributes. A user having + ACE4_WRITE_DATA or ACE4_WRITE_ATTRIBUTES will be allowed to set + the times associated with a file to the current server time. + + ACE4_DELETE + + Operation(s) affected: + + REMOVE + + Discussion: + + Permission to delete the file or directory. See + Section 6.2.1.3.2 for information on ACE4_DELETE and + ACE4_DELETE_CHILD interact. + + + + +Haynes & Noveck Standards Track [Page 64] + +RFC 7530 NFSv4 March 2015 + + + ACE4_READ_ACL + + Operation(s) affected: + + GETATTR of acl + + NVERIFY + + VERIFY + + Discussion: + + Permission to read the ACL. + + ACE4_WRITE_ACL + + Operation(s) affected: + + SETATTR of acl and mode + + Discussion: + + Permission to write the acl and mode attributes. + + ACE4_WRITE_OWNER + + Operation(s) affected: + + SETATTR of owner and owner_group + + Discussion: + + Permission to write the owner and owner_group attributes. On + UNIX systems, this is the ability to execute chown() and + chgrp(). + + + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 65] + +RFC 7530 NFSv4 March 2015 + + + ACE4_SYNCHRONIZE + + Operation(s) affected: + + NONE + + Discussion: + + Permission to use the file object as a synchronization + primitive for interprocess communication. This permission is + not enforced or interpreted by the NFSv4.0 server on behalf of + the client. + + Typically, the ACE4_SYNCHRONIZE permission is only meaningful + on local file systems, i.e., file systems not accessed via + NFSv4.0. The reason that the permission bit exists is that + some operating environments, such as Windows, use + ACE4_SYNCHRONIZE. + + For example, if a client copies a file that has + ACE4_SYNCHRONIZE set from a local file system to an NFSv4.0 + server, and then later copies the file from the NFSv4.0 server + to a local file system, it is likely that if ACE4_SYNCHRONIZE + was set in the original file, the client will want it set in + the second copy. The first copy will not have the permission + set unless the NFSv4.0 server has the means to set the + ACE4_SYNCHRONIZE bit. The second copy will not have the + permission set unless the NFSv4.0 server has the means to + retrieve the ACE4_SYNCHRONIZE bit. + + Server implementations need not provide the granularity of control + that is implied by this list of masks. For example, POSIX-based + systems might not distinguish ACE4_APPEND_DATA (the ability to append + to a file) from ACE4_WRITE_DATA (the ability to modify existing + contents); both masks would be tied to a single "write" permission. + When such a server returns attributes to the client, it would show + both ACE4_APPEND_DATA and ACE4_WRITE_DATA if and only if the write + permission is enabled. + + If a server receives a SETATTR request that it cannot accurately + implement, it should err in the direction of more restricted access, + except in the previously discussed cases of execute and read. For + example, suppose a server cannot distinguish overwriting data from + appending new data, as described in the previous paragraph. If a + client submits an ALLOW ACE where ACE4_APPEND_DATA is set but + ACE4_WRITE_DATA is not (or vice versa), the server should either turn + off ACE4_APPEND_DATA or reject the request with NFS4ERR_ATTRNOTSUPP. + + + + +Haynes & Noveck Standards Track [Page 66] + +RFC 7530 NFSv4 March 2015 + + +6.2.1.3.2. ACE4_DELETE versus ACE4_DELETE_CHILD + + Two access mask bits govern the ability to delete a directory entry: + ACE4_DELETE on the object itself (the "target") and ACE4_DELETE_CHILD + on the containing directory (the "parent"). + + Many systems also take the "sticky bit" (MODE4_SVTX) on a directory + to allow unlink only to a user that owns either the target or the + parent; on some such systems, the decision also depends on whether + the target is writable. + + Servers SHOULD allow unlink if either ACE4_DELETE is permitted on the + target or ACE4_DELETE_CHILD is permitted on the parent. (Note that + this is true even if the parent or target explicitly denies the other + of these permissions.) + + If the ACLs in question neither explicitly ALLOW nor DENY either of + the above, and if MODE4_SVTX is not set on the parent, then the + server SHOULD allow the removal if and only if ACE4_ADD_FILE is + permitted. In the case where MODE4_SVTX is set, the server may also + require the remover to own either the parent or the target, or may + require the target to be writable. + + This allows servers to support something close to traditional + UNIX-like semantics, with ACE4_ADD_FILE taking the place of the + write bit. + +6.2.1.4. ACE flag + + The bitmask constants used for the flag field are as follows: + + const ACE4_FILE_INHERIT_ACE = 0x00000001; + const ACE4_DIRECTORY_INHERIT_ACE = 0x00000002; + const ACE4_NO_PROPAGATE_INHERIT_ACE = 0x00000004; + const ACE4_INHERIT_ONLY_ACE = 0x00000008; + const ACE4_SUCCESSFUL_ACCESS_ACE_FLAG = 0x00000010; + const ACE4_FAILED_ACCESS_ACE_FLAG = 0x00000020; + const ACE4_IDENTIFIER_GROUP = 0x00000040; + + A server need not support any of these flags. If the server supports + flags that are similar to, but not exactly the same as, these flags, + the implementation may define a mapping between the protocol-defined + flags and the implementation-defined flags. + + For example, suppose a client tries to set an ACE with + ACE4_FILE_INHERIT_ACE set but not ACE4_DIRECTORY_INHERIT_ACE. If the + server does not support any form of ACL inheritance, the server + should reject the request with NFS4ERR_ATTRNOTSUPP. If the server + + + +Haynes & Noveck Standards Track [Page 67] + +RFC 7530 NFSv4 March 2015 + + + supports a single "inherit ACE" flag that applies to both files and + directories, the server may reject the request (i.e., requiring the + client to set both the file and directory inheritance flags). The + server may also accept the request and silently turn on the + ACE4_DIRECTORY_INHERIT_ACE flag. + +6.2.1.4.1. Discussion of Flag Bits + + ACE4_FILE_INHERIT_ACE + Any non-directory file in any subdirectory will get this ACE + inherited. + + ACE4_DIRECTORY_INHERIT_ACE + Can be placed on a directory and indicates that this ACE should be + added to each new directory created. + If this flag is set in an ACE in an ACL attribute to be set on a + non-directory file system object, the operation attempting to set + the ACL SHOULD fail with NFS4ERR_ATTRNOTSUPP. + + ACE4_INHERIT_ONLY_ACE + Can be placed on a directory but does not apply to the directory; + ALLOW and DENY ACEs with this bit set do not affect access to the + directory, and AUDIT and ALARM ACEs with this bit set do not + trigger log or alarm events. Such ACEs only take effect once they + are applied (with this bit cleared) to newly created files and + directories as specified by the above two flags. + If this flag is present on an ACE, but neither + ACE4_DIRECTORY_INHERIT_ACE nor ACE4_FILE_INHERIT_ACE is present, + then an operation attempting to set such an attribute SHOULD fail + with NFS4ERR_ATTRNOTSUPP. + + ACE4_NO_PROPAGATE_INHERIT_ACE + Can be placed on a directory. This flag tells the server that + inheritance of this ACE should stop at newly created child + directories. + + ACE4_SUCCESSFUL_ACCESS_ACE_FLAG + + ACE4_FAILED_ACCESS_ACE_FLAG + The ACE4_SUCCESSFUL_ACCESS_ACE_FLAG (SUCCESS) and + ACE4_FAILED_ACCESS_ACE_FLAG (FAILED) flag bits may be set only on + ACE4_SYSTEM_AUDIT_ACE_TYPE (AUDIT) and ACE4_SYSTEM_ALARM_ACE_TYPE + (ALARM) ACE types. If, during the processing of the file's ACL, + the server encounters an AUDIT or ALARM ACE that matches the + principal attempting the OPEN, the server notes that fact and + notes the presence, if any, of the SUCCESS and FAILED flags + encountered in the AUDIT or ALARM ACE. Once the server completes + the ACL processing, it then notes if the operation succeeded or + + + +Haynes & Noveck Standards Track [Page 68] + +RFC 7530 NFSv4 March 2015 + + + failed. If the operation succeeded, and if the SUCCESS flag was + set for a matching AUDIT or ALARM ACE, then the appropriate AUDIT + or ALARM event occurs. If the operation failed, and if the FAILED + flag was set for the matching AUDIT or ALARM ACE, then the + appropriate AUDIT or ALARM event occurs. Either or both of the + SUCCESS or FAILED can be set, but if neither is set, the AUDIT or + ALARM ACE is not useful. + + The previously described processing applies to ACCESS operations + even when they return NFS4_OK. For the purposes of AUDIT and + ALARM, we consider an ACCESS operation to be a "failure" if it + fails to return a bit that was requested and supported. + + ACE4_IDENTIFIER_GROUP + Indicates that the "who" refers to a GROUP as defined under UNIX + or a GROUP ACCOUNT as defined under Windows. Clients and servers + MUST ignore the ACE4_IDENTIFIER_GROUP flag on ACEs with a who + value equal to one of the special identifiers outlined in + Section 6.2.1.5. + +6.2.1.5. ACE Who + + The who field of an ACE is an identifier that specifies the principal + or principals to whom the ACE applies. It may refer to a user or a + group, with the flag bit ACE4_IDENTIFIER_GROUP specifying which. + + There are several special identifiers that need to be understood + universally, rather than in the context of a particular DNS domain. + Some of these identifiers cannot be understood when an NFS client + accesses the server but have meaning when a local process accesses + the file. The ability to display and modify these permissions is + permitted over NFS, even if none of the access methods on the server + understand the identifiers. + + + + + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 69] + +RFC 7530 NFSv4 March 2015 + + + +---------------+---------------------------------------------------+ + | Who | Description | + +---------------+---------------------------------------------------+ + | OWNER | The owner of the file. | + | GROUP | The group associated with the file. | + | EVERYONE | The world, including the owner and owning group. | + | INTERACTIVE | Accessed from an interactive terminal. | + | NETWORK | Accessed via the network. | + | DIALUP | Accessed as a dialup user to the server. | + | BATCH | Accessed from a batch job. | + | ANONYMOUS | Accessed without any authentication. | + | AUTHENTICATED | Any authenticated user (opposite of ANONYMOUS). | + | SERVICE | Access from a system service. | + +---------------+---------------------------------------------------+ + + Table 5: Special Identifiers + + To avoid conflict, these special identifiers are distinguished by an + appended "@" and should appear in the form "xxxx@" (with no domain + name after the "@") -- for example, ANONYMOUS@. + + The ACE4_IDENTIFIER_GROUP flag MUST be ignored on entries with these + special identifiers. When encoding entries with these special + identifiers, the ACE4_IDENTIFIER_GROUP flag SHOULD be set to zero. + +6.2.1.5.1. Discussion of EVERYONE@ + + It is important to note that "EVERYONE@" is not equivalent to the + UNIX "other" entity. This is because, by definition, UNIX "other" + does not include the owner or owning group of a file. "EVERYONE@" + means literally everyone, including the owner or owning group. + +6.2.2. Attribute 33: mode + + The NFSv4.0 mode attribute is based on the UNIX mode bits. The + following bits are defined: + + const MODE4_SUID = 0x800; /* set user id on execution */ + const MODE4_SGID = 0x400; /* set group id on execution */ + const MODE4_SVTX = 0x200; /* save text even after use */ + const MODE4_RUSR = 0x100; /* read permission: owner */ + const MODE4_WUSR = 0x080; /* write permission: owner */ + const MODE4_XUSR = 0x040; /* execute permission: owner */ + const MODE4_RGRP = 0x020; /* read permission: group */ + const MODE4_WGRP = 0x010; /* write permission: group */ + const MODE4_XGRP = 0x008; /* execute permission: group */ + + + + + +Haynes & Noveck Standards Track [Page 70] + +RFC 7530 NFSv4 March 2015 + + + const MODE4_ROTH = 0x004; /* read permission: other */ + const MODE4_WOTH = 0x002; /* write permission: other */ + const MODE4_XOTH = 0x001; /* execute permission: other */ + + Bits MODE4_RUSR, MODE4_WUSR, and MODE4_XUSR apply to the principal + identified in the owner attribute. Bits MODE4_RGRP, MODE4_WGRP, and + MODE4_XGRP apply to principals identified in the owner_group + attribute but who are not identified in the owner attribute. Bits + MODE4_ROTH, MODE4_WOTH, and MODE4_XOTH apply to any principal that + does not match that in the owner attribute and does not have a group + matching that of the owner_group attribute. + + Bits within the mode other than those specified above are not defined + by this protocol. A server MUST NOT return bits other than those + defined above in a GETATTR or READDIR operation, and it MUST return + NFS4ERR_INVAL if bits other than those defined above are set in a + SETATTR, CREATE, OPEN, VERIFY, or NVERIFY operation. + +6.3. Common Methods + + The requirements in this section will be referred to in future + sections, especially Section 6.4. + +6.3.1. Interpreting an ACL + +6.3.1.1. Server Considerations + + The server uses the algorithm described in Section 6.2.1 to determine + whether an ACL allows access to an object. However, the ACL may not + be the sole determiner of access. For example: + + o In the case of a file system exported as read-only, the server may + deny write permissions even though an object's ACL grants it. + + o Server implementations MAY grant ACE4_WRITE_ACL and ACE4_READ_ACL + permissions to prevent a situation from arising in which there is + no valid way to ever modify the ACL. + + o All servers will allow a user the ability to read the data of the + file when only the execute permission is granted (i.e., if the ACL + denies the user ACE4_READ_DATA access and allows the user + ACE4_EXECUTE, the server will allow the user to read the data of + the file). + + + + + + + + +Haynes & Noveck Standards Track [Page 71] + +RFC 7530 NFSv4 March 2015 + + + o Many servers have the notion of owner-override, in which the owner + of the object is allowed to override accesses that are denied by + the ACL. This may be helpful, for example, to allow users + continued access to open files on which the permissions have + changed. + + o Many servers have the notion of a "superuser" that has privileges + beyond an ordinary user. The superuser may be able to read or + write data or metadata in ways that would not be permitted by + the ACL. + +6.3.1.2. Client Considerations + + Clients SHOULD NOT do their own access checks based on their + interpretation of the ACL but rather use the OPEN and ACCESS + operations to do access checks. This allows the client to act on the + results of having the server determine whether or not access should + be granted based on its interpretation of the ACL. + + Clients must be aware of situations in which an object's ACL will + define a certain access even though the server will not have adequate + information to enforce it. For example, the server has no way of + determining whether a particular OPEN reflects a user's open for read + access or is done as part of executing the file in question. In such + situations, the client needs to do its part in the enforcement of + access as defined by the ACL. To do this, the client will send the + appropriate ACCESS operation (or use a cached previous determination) + prior to servicing the request of the user or application in order to + determine whether the user or application should be granted the + access requested. For examples in which the ACL may define accesses + that the server does not enforce, see Section 6.3.1.1. + +6.3.2. Computing a mode Attribute from an ACL + + The following method can be used to calculate the MODE4_R*, MODE4_W*, + and MODE4_X* bits of a mode attribute, based upon an ACL. + + First, for each of the special identifiers OWNER@, GROUP@, and + EVERYONE@, evaluate the ACL in order, considering only ALLOW and DENY + ACEs for the identifier EVERYONE@ and for the identifier under + consideration. The result of the evaluation will be an NFSv4 ACL + mask showing exactly which bits are permitted to that identifier. + + + + + + + + + +Haynes & Noveck Standards Track [Page 72] + +RFC 7530 NFSv4 March 2015 + + + Then translate the calculated mask for OWNER@, GROUP@, and EVERYONE@ + into mode bits for the user, group, and other, respectively, as + follows: + + 1. Set the read bit (MODE4_RUSR, MODE4_RGRP, or MODE4_ROTH) if and + only if ACE4_READ_DATA is set in the corresponding mask. + + 2. Set the write bit (MODE4_WUSR, MODE4_WGRP, or MODE4_WOTH) if and + only if ACE4_WRITE_DATA and ACE4_APPEND_DATA are both set in the + corresponding mask. + + 3. Set the execute bit (MODE4_XUSR, MODE4_XGRP, or MODE4_XOTH), if + and only if ACE4_EXECUTE is set in the corresponding mask. + +6.3.2.1. Discussion + + Some server implementations also add bits permitted to named users + and groups to the group bits (MODE4_RGRP, MODE4_WGRP, and + MODE4_XGRP). + + Implementations are discouraged from doing this, because it has been + found to cause confusion for users who see members of a file's group + denied access that the mode bits appear to allow. (The presence of + DENY ACEs may also lead to such behavior, but DENY ACEs are expected + to be more rarely used.) + + The same user confusion seen when fetching the mode also results if + setting the mode does not effectively control permissions for the + owner, group, and other users; this motivates some of the + requirements that follow. + +6.4. Requirements + + The server that supports both mode and ACL must take care to + synchronize the MODE4_*USR, MODE4_*GRP, and MODE4_*OTH bits with the + ACEs that have respective who fields of "OWNER@", "GROUP@", and + "EVERYONE@" so that the client can see that semantically equivalent + access permissions exist whether the client asks for just the ACL or + any of the owner, owner_group, and mode attributes. + + Many requirements refer to Section 6.3.2, but note that the methods + have behaviors specified with "SHOULD". This is intentional, to + avoid invalidating existing implementations that compute the mode + according to the withdrawn POSIX ACL draft ([P1003.1e]), rather than + by actual permissions on owner, group, and other. + + + + + + +Haynes & Noveck Standards Track [Page 73] + +RFC 7530 NFSv4 March 2015 + + +6.4.1. Setting the mode and/or ACL Attributes + +6.4.1.1. Setting mode and Not ACL + + When any of the nine low-order mode bits are changed because the mode + attribute was set, and no ACL attribute is explicitly set, the acl + attribute must be modified in accordance with the updated value of + those bits. This must happen even if the value of the low-order bits + is the same after the mode is set as before. + + Note that any AUDIT or ALARM ACEs are unaffected by changes to the + mode. + + In cases in which the permissions bits are subject to change, the acl + attribute MUST be modified such that the mode computed via the method + described in Section 6.3.2 yields the low-order nine bits (MODE4_R*, + MODE4_W*, MODE4_X*) of the mode attribute as modified by the change + attribute. The ACL attributes SHOULD also be modified such that: + + 1. If MODE4_RGRP is not set, entities explicitly listed in the ACL + other than OWNER@ and EVERYONE@ SHOULD NOT be granted + ACE4_READ_DATA. + + 2. If MODE4_WGRP is not set, entities explicitly listed in the ACL + other than OWNER@ and EVERYONE@ SHOULD NOT be granted + ACE4_WRITE_DATA or ACE4_APPEND_DATA. + + 3. If MODE4_XGRP is not set, entities explicitly listed in the ACL + other than OWNER@ and EVERYONE@ SHOULD NOT be granted + ACE4_EXECUTE. + + Access mask bits other than those listed above, appearing in ALLOW + ACEs, MAY also be disabled. + + Note that ACEs with the flag ACE4_INHERIT_ONLY_ACE set do not affect + the permissions of the ACL itself, nor do ACEs of the types AUDIT and + ALARM. As such, it is desirable to leave these ACEs unmodified when + modifying the ACL attributes. + + Also note that the requirement may be met by discarding the acl in + favor of an ACL that represents the mode and only the mode. This is + permitted, but it is preferable for a server to preserve as much of + the ACL as possible without violating the above requirements. + Discarding the ACL makes it effectively impossible for a file created + with a mode attribute to inherit an ACL (see Section 6.4.3). + + + + + + +Haynes & Noveck Standards Track [Page 74] + +RFC 7530 NFSv4 March 2015 + + +6.4.1.2. Setting ACL and Not mode + + When setting the acl and not setting the mode attribute, the + permission bits of the mode need to be derived from the ACL. In this + case, the ACL attribute SHOULD be set as given. The nine low-order + bits of the mode attribute (MODE4_R*, MODE4_W*, MODE4_X*) MUST be + modified to match the result of the method described in + Section 6.3.2. The three high-order bits of the mode (MODE4_SUID, + MODE4_SGID, MODE4_SVTX) SHOULD remain unchanged. + +6.4.1.3. Setting Both ACL and mode + + When setting both the mode and the acl attribute in the same + operation, the attributes MUST be applied in this order: mode, then + ACL. The mode-related attribute is set as given, then the ACL + attribute is set as given, possibly changing the final mode, as + described above in Section 6.4.1.2. + +6.4.2. Retrieving the mode and/or ACL Attributes + + This section applies only to servers that support both the mode and + ACL attributes. + + Some server implementations may have a concept of "objects without + ACLs", meaning that all permissions are granted and denied according + to the mode attribute, and that no ACL attribute is stored for that + object. If an ACL attribute is requested of such a server, the + server SHOULD return an ACL that does not conflict with the mode; + that is to say, the ACL returned SHOULD represent the nine low-order + bits of the mode attribute (MODE4_R*, MODE4_W*, MODE4_X*) as + described in Section 6.3.2. + + For other server implementations, the ACL attribute is always present + for every object. Such servers SHOULD store at least the three + high-order bits of the mode attribute (MODE4_SUID, MODE4_SGID, + MODE4_SVTX). The server SHOULD return a mode attribute if one is + requested, and the low-order nine bits of the mode (MODE4_R*, + MODE4_W*, MODE4_X*) MUST match the result of applying the method in + Section 6.3.2 to the ACL attribute. + +6.4.3. Creating New Objects + + If a server supports any ACL attributes, it may use the ACL + attributes on the parent directory to compute an initial ACL + attribute for a newly created object. This will be referred to as + the inherited ACL within this section. The act of adding one or more + + + + + +Haynes & Noveck Standards Track [Page 75] + +RFC 7530 NFSv4 March 2015 + + + ACEs to the inherited ACL that are based upon ACEs in the parent + directory's ACL will be referred to as inheriting an ACE within this + section. + + In the presence or absence of the mode and ACL attributes, the + behavior of CREATE and OPEN SHOULD be: + + 1. If just the mode is given in the call: + + In this case, inheritance SHOULD take place, but the mode MUST be + applied to the inherited ACL as described in Section 6.4.1.1, + thereby modifying the ACL. + + 2. If just the ACL is given in the call: + + In this case, inheritance SHOULD NOT take place, and the ACL as + defined in the CREATE or OPEN will be set without modification, + and the mode modified as in Section 6.4.1.2. + + 3. If both mode and ACL are given in the call: + + In this case, inheritance SHOULD NOT take place, and both + attributes will be set as described in Section 6.4.1.3. + + 4. If neither mode nor ACL is given in the call: + + In the case where an object is being created without any initial + attributes at all, e.g., an OPEN operation with an opentype4 of + OPEN4_CREATE and a createmode4 of EXCLUSIVE4, inheritance SHOULD + NOT take place. Instead, the server SHOULD set permissions to + deny all access to the newly created object. It is expected that + the appropriate client will set the desired attributes in a + subsequent SETATTR operation, and the server SHOULD allow that + operation to succeed, regardless of what permissions the object + is created with. For example, an empty ACL denies all + permissions, but the server should allow the owner's SETATTR to + succeed even though WRITE_ACL is implicitly denied. + + In other cases, inheritance SHOULD take place, and no + modifications to the ACL will happen. The mode attribute, if + supported, MUST be as computed via the method described in + Section 6.3.2, with the MODE4_SUID, MODE4_SGID, and MODE4_SVTX + bits clear. If no inheritable ACEs exist on the parent + directory, the rules for creating acl attributes are + implementation defined. + + + + + + +Haynes & Noveck Standards Track [Page 76] + +RFC 7530 NFSv4 March 2015 + + +6.4.3.1. The Inherited ACL + + If the object being created is not a directory, the inherited ACL + SHOULD NOT inherit ACEs from the parent directory ACL unless the + ACE4_FILE_INHERIT_FLAG is set. + + If the object being created is a directory, the inherited ACL should + inherit all inheritable ACEs from the parent directory, i.e., those + that have the ACE4_FILE_INHERIT_ACE or ACE4_DIRECTORY_INHERIT_ACE + flag set. If the inheritable ACE has ACE4_FILE_INHERIT_ACE set, but + ACE4_DIRECTORY_INHERIT_ACE is clear, the inherited ACE on the newly + created directory MUST have the ACE4_INHERIT_ONLY_ACE flag set to + prevent the directory from being affected by ACEs meant for + non-directories. + + When a new directory is created, the server MAY split any inherited + ACE that is both inheritable and effective (in other words, that has + neither ACE4_INHERIT_ONLY_ACE nor ACE4_NO_PROPAGATE_INHERIT_ACE set) + into two ACEs -- one with no inheritance flags, and one with + ACE4_INHERIT_ONLY_ACE set. This makes it simpler to modify the + effective permissions on the directory without modifying the ACE that + is to be inherited to the new directory's children. + +7. NFS Server Namespace + +7.1. Server Exports + + On a UNIX server, the namespace describes all the files reachable by + pathnames under the root directory or "/". On a Windows server, the + namespace constitutes all the files on disks named by mapped disk + letters. NFS server administrators rarely make the entire server's + file system namespace available to NFS clients. More often, portions + of the namespace are made available via an "export" feature. In + previous versions of the NFS protocol, the root filehandle for each + export is obtained through the MOUNT protocol; the client sends a + string that identifies an object in the exported namespace, and the + server returns the root filehandle for it. The MOUNT protocol + supports an EXPORTS procedure that will enumerate the server's + exports. + +7.2. Browsing Exports + + The NFSv4 protocol provides a root filehandle that clients can use to + obtain filehandles for these exports via a multi-component LOOKUP. A + common user experience is to use a graphical user interface (perhaps + a file "Open" dialog window) to find a file via progressive browsing + + + + + +Haynes & Noveck Standards Track [Page 77] + +RFC 7530 NFSv4 March 2015 + + + through a directory tree. The client must be able to move from one + export to another export via single-component, progressive LOOKUP + operations. + + This style of browsing is not well supported by the NFSv2 and NFSv3 + protocols. The client expects all LOOKUP operations to remain within + a single-server file system. For example, the device attribute will + not change. This prevents a client from taking namespace paths that + span exports. + + An automounter on the client can obtain a snapshot of the server's + namespace using the EXPORTS procedure of the MOUNT protocol. If it + understands the server's pathname syntax, it can create an image of + the server's namespace on the client. The parts of the namespace + that are not exported by the server are filled in with a "pseudo-file + system" that allows the user to browse from one mounted file system + to another. There is a drawback to this representation of the + server's namespace on the client: it is static. If the server + administrator adds a new export, the client will be unaware of it. + +7.3. Server Pseudo-File System + + NFSv4 servers avoid this namespace inconsistency by presenting all + the exports within the framework of a single-server namespace. An + NFSv4 client uses LOOKUP and READDIR operations to browse seamlessly + from one export to another. Portions of the server namespace that + are not exported are bridged via a "pseudo-file system" that provides + a view of exported directories only. A pseudo-file system has a + unique fsid and behaves like a normal, read-only file system. + + Based on the construction of the server's namespace, it is possible + that multiple pseudo-file systems may exist. For example: + + /a pseudo-file system + /a/b real file system + /a/b/c pseudo-file system + /a/b/c/d real file system + + Each of the pseudo-file systems are considered separate entities and + therefore will have a unique fsid. + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 78] + +RFC 7530 NFSv4 March 2015 + + +7.4. Multiple Roots + + The DOS and Windows operating environments are sometimes described as + having "multiple roots". File systems are commonly represented as + disk letters. MacOS represents file systems as top-level names. + NFSv4 servers for these platforms can construct a pseudo-file system + above these root names so that disk letters or volume names are + simply directory names in the pseudo-root. + +7.5. Filehandle Volatility + + The nature of the server's pseudo-file system is that it is a logical + representation of file system(s) available from the server. + Therefore, the pseudo-file system is most likely constructed + dynamically when the server is first instantiated. It is expected + that the pseudo-file system may not have an on-disk counterpart from + which persistent filehandles could be constructed. Even though it is + preferable that the server provide persistent filehandles for the + pseudo-file system, the NFS client should expect that pseudo-file + system filehandles are volatile. This can be confirmed by checking + the associated "fh_expire_type" attribute for those filehandles in + question. If the filehandles are volatile, the NFS client must be + prepared to recover a filehandle value (e.g., with a multi-component + LOOKUP) when receiving an error of NFS4ERR_FHEXPIRED. + +7.6. Exported Root + + If the server's root file system is exported, one might conclude that + a pseudo-file system is not needed. This would be wrong. Assume the + following file systems on a server: + + / disk1 (exported) + /a disk2 (not exported) + /a/b disk3 (exported) + + Because disk2 is not exported, disk3 cannot be reached with simple + LOOKUPs. The server must bridge the gap with a pseudo-file system. + +7.7. Mount Point Crossing + + The server file system environment may be constructed in such a way + that one file system contains a directory that is 'covered' or + mounted upon by a second file system. For example: + + /a/b (file system 1) + /a/b/c/d (file system 2) + + + + + +Haynes & Noveck Standards Track [Page 79] + +RFC 7530 NFSv4 March 2015 + + + The pseudo-file system for this server may be constructed to + look like: + + / (placeholder/not exported) + /a/b (file system 1) + /a/b/c/d (file system 2) + + It is the server's responsibility to present the pseudo-file system + that is complete to the client. If the client sends a LOOKUP request + for the path "/a/b/c/d", the server's response is the filehandle of + the file system "/a/b/c/d". In previous versions of the NFS + protocol, the server would respond with the filehandle of directory + "/a/b/c/d" within the file system "/a/b". + + The NFS client will be able to determine if it crosses a server mount + point by a change in the value of the "fsid" attribute. + +7.8. Security Policy and Namespace Presentation + + Because NFSv4 clients possess the ability to change the security + mechanisms used, after determining what is allowed, by using SECINFO + the server SHOULD NOT present a different view of the namespace based + on the security mechanism being used by a client. Instead, it should + present a consistent view and return NFS4ERR_WRONGSEC if an attempt + is made to access data with an inappropriate security mechanism. + + If security considerations make it necessary to hide the existence of + a particular file system, as opposed to all of the data within it, + the server can apply the security policy of a shared resource in the + server's namespace to components of the resource's ancestors. For + example: + + / (placeholder/not exported) + /a/b (file system 1) + /a/b/MySecretProject (file system 2) + + The /a/b/MySecretProject directory is a real file system and is the + shared resource. Suppose the security policy for /a/b/ + MySecretProject is Kerberos with integrity and it is desired to limit + knowledge of the existence of this file system. In this case, the + server should apply the same security policy to /a/b. This allows + for knowledge of the existence of a file system to be secured when + desirable. + + For the case of the use of multiple, disjoint security mechanisms in + the server's resources, applying that sort of policy would result in + the higher-level file system not being accessible using any security + + + + +Haynes & Noveck Standards Track [Page 80] + +RFC 7530 NFSv4 March 2015 + + + flavor. Therefore, that sort of configuration is not compatible with + hiding the existence (as opposed to the contents) from clients using + multiple disjoint sets of security flavors. + + In other circumstances, a desirable policy is for the security of a + particular object in the server's namespace to include the union of + all security mechanisms of all direct descendants. A common and + convenient practice, unless strong security requirements dictate + otherwise, is to make the entire pseudo-file system accessible by all + of the valid security mechanisms. + + Where there is concern about the security of data on the network, + clients should use strong security mechanisms to access the + pseudo-file system in order to prevent man-in-the-middle attacks. + +8. Multi-Server Namespace + + NFSv4 supports attributes that allow a namespace to extend beyond the + boundaries of a single server. It is RECOMMENDED that clients and + servers support construction of such multi-server namespaces. Use of + such multi-server namespaces is optional, however, and for many + purposes, single-server namespaces are perfectly acceptable. Use of + multi-server namespaces can provide many advantages, however, by + separating a file system's logical position in a namespace from the + (possibly changing) logistical and administrative considerations that + result in particular file systems being located on particular + servers. + +8.1. Location Attributes + + NFSv4 contains RECOMMENDED attributes that allow file systems on one + server to be associated with one or more instances of that file + system on other servers. These attributes specify such file system + instances by specifying a server address target (as either a DNS name + representing one or more IP addresses, or a literal IP address), + together with the path of that file system within the associated + single-server namespace. + + The fs_locations RECOMMENDED attribute allows specification of the + file system locations where the data corresponding to a given file + system may be found. + +8.2. File System Presence or Absence + + A given location in an NFSv4 namespace (typically but not necessarily + a multi-server namespace) can have a number of file system instance + locations associated with it via the fs_locations attribute. There + may also be an actual current file system at that location, + + + +Haynes & Noveck Standards Track [Page 81] + +RFC 7530 NFSv4 March 2015 + + + accessible via normal namespace operations (e.g., LOOKUP). In this + case, the file system is said to be "present" at that position in the + namespace, and clients will typically use it, reserving use of + additional locations specified via the location-related attributes to + situations in which the principal location is no longer available. + + When there is no actual file system at the namespace location in + question, the file system is said to be "absent". An absent file + system contains no files or directories other than the root. Any + reference to it, except to access a small set of attributes useful in + determining alternative locations, will result in an error, + NFS4ERR_MOVED. Note that if the server ever returns the error + NFS4ERR_MOVED, it MUST support the fs_locations attribute. + + While the error name suggests that we have a case of a file system + that once was present, and has only become absent later, this is only + one possibility. A position in the namespace may be permanently + absent with the set of file system(s) designated by the location + attributes being the only realization. The name NFS4ERR_MOVED + reflects an earlier, more limited conception of its function, but + this error will be returned whenever the referenced file system is + absent, whether it has moved or simply never existed. + + Except in the case of GETATTR-type operations (to be discussed + later), when the current filehandle at the start of an operation is + within an absent file system, that operation is not performed and the + error NFS4ERR_MOVED is returned, to indicate that the file system is + absent on the current server. + + Because a GETFH cannot succeed if the current filehandle is within an + absent file system, filehandles within an absent file system cannot + be transferred to the client. When a client does have filehandles + within an absent file system, it is the result of obtaining them when + the file system was present, and having the file system become absent + subsequently. + + It should be noted that because the check for the current filehandle + being within an absent file system happens at the start of every + operation, operations that change the current filehandle so that it + is within an absent file system will not result in an error. This + allows such combinations as PUTFH-GETATTR and LOOKUP-GETATTR to be + used to get attribute information, particularly location attribute + information, as discussed below. + + + + + + + + +Haynes & Noveck Standards Track [Page 82] + +RFC 7530 NFSv4 March 2015 + + +8.3. Getting Attributes for an Absent File System + + When a file system is absent, most attributes are not available, but + it is necessary to allow the client access to the small set of + attributes that are available, and most particularly that which gives + information about the correct current locations for this file system, + fs_locations. + +8.3.1. GETATTR within an Absent File System + + As mentioned above, an exception is made for GETATTR in that + attributes may be obtained for a filehandle within an absent file + system. This exception only applies if the attribute mask contains + at least the fs_locations attribute bit, which indicates that the + client is interested in a result regarding an absent file system. If + it is not requested, GETATTR will result in an NFS4ERR_MOVED error. + + When a GETATTR is done on an absent file system, the set of supported + attributes is very limited. Many attributes, including those that + are normally REQUIRED, will not be available on an absent file + system. In addition to the fs_locations attribute, the following + attributes SHOULD be available on absent file systems. In the case + of RECOMMENDED attributes, they should be available at least to the + same degree that they are available on present file systems. + + fsid: This attribute should be provided so that the client can + determine file system boundaries, including, in particular, the + boundary between present and absent file systems. This value must + be different from any other fsid on the current server and need + have no particular relationship to fsids on any particular + destination to which the client might be directed. + + mounted_on_fileid: For objects at the top of an absent file system, + this attribute needs to be available. Since the fileid is within + the present parent file system, there should be no need to + reference the absent file system to provide this information. + + Other attributes SHOULD NOT be made available for absent file + systems, even when it is possible to provide them. The server should + not assume that more information is always better and should avoid + gratuitously providing additional information. + + When a GETATTR operation includes a bitmask for the attribute + fs_locations, but where the bitmask includes attributes that are not + supported, GETATTR will not return an error but will return the mask + of the actual attributes supported with the results. + + + + + +Haynes & Noveck Standards Track [Page 83] + +RFC 7530 NFSv4 March 2015 + + + Handling of VERIFY/NVERIFY is similar to GETATTR in that if the + attribute mask does not include fs_locations the error NFS4ERR_MOVED + will result. It differs in that any appearance in the attribute mask + of an attribute not supported for an absent file system (and note + that this will include some normally REQUIRED attributes) will also + cause an NFS4ERR_MOVED result. + +8.3.2. READDIR and Absent File Systems + + A READDIR performed when the current filehandle is within an absent + file system will result in an NFS4ERR_MOVED error, since, unlike the + case of GETATTR, no such exception is made for READDIR. + + Attributes for an absent file system may be fetched via a READDIR for + a directory in a present file system, when that directory contains + the root directories of one or more absent file systems. In this + case, the handling is as follows: + + o If the attribute set requested includes fs_locations, then the + fetching of attributes proceeds normally, and no NFS4ERR_MOVED + indication is returned even when the rdattr_error attribute is + requested. + + o If the attribute set requested does not include fs_locations, then + if the rdattr_error attribute is requested, each directory entry + for the root of an absent file system will report NFS4ERR_MOVED as + the value of the rdattr_error attribute. + + o If the attribute set requested does not include either of the + attributes fs_locations or rdattr_error, then the occurrence of + the root of an absent file system within the directory will result + in the READDIR failing with an NFS4ERR_MOVED error. + + o The unavailability of an attribute because of a file system's + absence, even one that is ordinarily REQUIRED, does not result in + any error indication. The set of attributes returned for the root + directory of the absent file system in that case is simply + restricted to those actually available. + +8.4. Uses of Location Information + + The location-bearing attribute of fs_locations provides, together + with the possibility of absent file systems, a number of important + facilities in providing reliable, manageable, and scalable data + access. + + + + + + +Haynes & Noveck Standards Track [Page 84] + +RFC 7530 NFSv4 March 2015 + + + When a file system is present, these attributes can provide + alternative locations, to be used to access the same data, in the + event of server failures, communications problems, or other + difficulties that make continued access to the current file system + impossible or otherwise impractical. Under some circumstances, + multiple alternative locations may be used simultaneously to provide + higher-performance access to the file system in question. Provision + of such alternative locations is referred to as "replication", + although there are cases in which replicated sets of data are not in + fact present and the replicas are instead different paths to the same + data. + + When a file system is present and subsequently becomes absent, + clients can be given the opportunity to have continued access to + their data, at an alternative location. Transfer of the file system + contents to the new location is referred to as "migration". See + Section 8.4.2 for details. + + Alternative locations may be physical replicas of the file system + data or alternative communication paths to the same server or, in the + case of various forms of server clustering, another server providing + access to the same physical file system. The client's + responsibilities in dealing with this transition depend on the + specific nature of the new access path as well as how and whether + data was in fact migrated. These issues will be discussed in detail + below. + + Where a file system was not previously present, specification of file + system location provides a means by which file systems located on one + server can be associated with a namespace defined by another server, + thus allowing a general multi-server namespace facility. A + designation of such a location, in place of an absent file system, is + called a "referral". + + Because client support for location-related attributes is OPTIONAL, a + server may (but is not required to) take action to hide migration and + referral events from such clients, by acting as a proxy, for example. + +8.4.1. File System Replication + + The fs_locations attribute provides alternative locations, to be used + to access data in place of, or in addition to, the current file + system instance. On first access to a file system, the client should + obtain the value of the set of alternative locations by interrogating + the fs_locations attribute. + + + + + + +Haynes & Noveck Standards Track [Page 85] + +RFC 7530 NFSv4 March 2015 + + + In the event that server failures, communications problems, or other + difficulties make continued access to the current file system + impossible or otherwise impractical, the client can use the + alternative locations as a way to get continued access to its data. + Multiple locations may be used simultaneously, to provide higher + performance through the exploitation of multiple paths between client + and target file system. + + Multiple server addresses, whether they are derived from a single + entry with a DNS name representing a set of IP addresses or from + multiple entries each with its own server address, may correspond to + the same actual server. + +8.4.2. File System Migration + + When a file system is present and becomes absent, clients can be + given the opportunity to have continued access to their data, at an + alternative location, as specified by the fs_locations attribute. + Typically, a client will be accessing the file system in question, + get an NFS4ERR_MOVED error, and then use the fs_locations attribute + to determine the new location of the data. + + Such migration can be helpful in providing load balancing or general + resource reallocation. The protocol does not specify how the file + system will be moved between servers. It is anticipated that a + number of different server-to-server transfer mechanisms might be + used, with the choice left to the server implementer. The NFSv4 + protocol specifies the method used to communicate the migration event + between client and server. + + When an alternative location is designated as the target for + migration, it must designate the same data. Where file systems are + writable, a change made on the original file system must be visible + on all migration targets. Where a file system is not writable but + represents a read-only copy (possibly periodically updated) of a + writable file system, similar requirements apply to the propagation + of updates. Any change visible in the original file system must + already be effected on all migration targets, to avoid any + possibility that a client, in effecting a transition to the migration + target, will see any reversion in file system state. + +8.4.3. Referrals + + Referrals provide a way of placing a file system in a location within + the namespace essentially without respect to its physical location on + a given server. This allows a single server or a set of servers to + present a multi-server namespace that encompasses file systems + + + + +Haynes & Noveck Standards Track [Page 86] + +RFC 7530 NFSv4 March 2015 + + + located on multiple servers. Some likely uses of this include + establishment of site-wide or organization-wide namespaces, or even + knitting such together into a truly global namespace. + + Referrals occur when a client determines, upon first referencing a + position in the current namespace, that it is part of a new file + system and that the file system is absent. When this occurs, + typically by receiving the error NFS4ERR_MOVED, the actual location + or locations of the file system can be determined by fetching the + fs_locations attribute. + + The location-related attribute may designate a single file system + location or multiple file system locations, to be selected based on + the needs of the client. + + Use of multi-server namespaces is enabled by NFSv4 but is not + required. The use of multi-server namespaces and their scope will + depend on the applications used and system administration + preferences. + + Multi-server namespaces can be established by a single server + providing a large set of referrals to all of the included file + systems. Alternatively, a single multi-server namespace may be + administratively segmented with separate referral file systems (on + separate servers) for each separately administered portion of the + namespace. The top-level referral file system or any segment may use + replicated referral file systems for higher availability. + + Generally, multi-server namespaces are for the most part uniform, in + that the same data made available to one client at a given location + in the namespace is made available to all clients at that location. + +8.5. Location Entries and Server Identity + + As mentioned above, a single location entry may have a server address + target in the form of a DNS name that may represent multiple IP + addresses, while multiple location entries may have their own server + address targets that reference the same server. + + When multiple addresses for the same server exist, the client may + assume that for each file system in the namespace of a given server + network address, there exist file systems at corresponding namespace + locations for each of the other server network addresses. It may do + this even in the absence of explicit listing in fs_locations. Such + corresponding file system locations can be used as alternative + locations, just as those explicitly specified via the fs_locations + attribute. + + + + +Haynes & Noveck Standards Track [Page 87] + +RFC 7530 NFSv4 March 2015 + + + If a single location entry designates multiple server IP addresses, + the client should choose a single one to use. When two server + addresses are designated by a single location entry and they + correspond to different servers, this normally indicates some sort of + misconfiguration, and so the client should avoid using such location + entries when alternatives are available. When they are not, clients + should pick one of the IP addresses and use it, without using others + that are not directed to the same server. + +8.6. Additional Client-Side Considerations + + When clients make use of servers that implement referrals, + replication, and migration, care should be taken that a user who + mounts a given file system that includes a referral or a relocated + file system continues to see a coherent picture of that user-side + file system despite the fact that it contains a number of server-side + file systems that may be on different servers. + + One important issue is upward navigation from the root of a + server-side file system to its parent (specified as ".." in UNIX), in + the case in which it transitions to that file system as a result of + referral, migration, or a transition as a result of replication. + When the client is at such a point, and it needs to ascend to the + parent, it must go back to the parent as seen within the multi-server + namespace rather than sending a LOOKUPP operation to the server, + which would result in the parent within that server's single-server + namespace. In order to do this, the client needs to remember the + filehandles that represent such file system roots and use these + instead of issuing a LOOKUPP operation to the current server. This + will allow the client to present to applications a consistent + namespace, where upward navigation and downward navigation are + consistent. + + Another issue concerns refresh of referral locations. When referrals + are used extensively, they may change as server configurations + change. It is expected that clients will cache information related + to traversing referrals so that future client-side requests are + resolved locally without server communication. This is usually + rooted in client-side name lookup caching. Clients should + periodically purge this data for referral points in order to detect + changes in location information. + + A potential problem exists if a client were to allow an open-owner to + have state on multiple file systems on a server, in that it is + unclear how the sequence numbers associated with open-owners are to + be dealt with, in the event of transparent state migration. A client + can avoid such a situation if it ensures that any use of an + open-owner is confined to a single file system. + + + +Haynes & Noveck Standards Track [Page 88] + +RFC 7530 NFSv4 March 2015 + + + A server MAY decline to migrate state associated with open-owners + that span multiple file systems. In cases in which the server + chooses not to migrate such state, the server MUST return + NFS4ERR_BAD_STATEID when the client uses those stateids on the new + server. + + The server MUST return NFS4ERR_STALE_STATEID when the client uses + those stateids on the old server, regardless of whether migration has + occurred or not. + +8.7. Effecting File System Referrals + + Referrals are effected when an absent file system is encountered and + one or more alternative locations are made available by the + fs_locations attribute. The client will typically get an + NFS4ERR_MOVED error, fetch the appropriate location information, and + proceed to access the file system on a different server, even though + it retains its logical position within the original namespace. + Referrals differ from migration events in that they happen only when + the client has not previously referenced the file system in question + (so there is nothing to transition). Referrals can only come into + effect when an absent file system is encountered at its root. + + The examples given in the sections below are somewhat artificial in + that an actual client will not typically do a multi-component lookup + but will have cached information regarding the upper levels of the + name hierarchy. However, these example are chosen to make the + required behavior clear and easy to put within the scope of a small + number of requests, without getting unduly into details of how + specific clients might choose to cache things. + +8.7.1. Referral Example (LOOKUP) + + Let us suppose that the following COMPOUND is sent in an environment + in which /this/is/the/path is absent from the target server. This + may be for a number of reasons. It may be the case that the file + system has moved, or it may be the case that the target server is + functioning mainly, or solely, to refer clients to the servers on + which various file systems are located. + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 89] + +RFC 7530 NFSv4 March 2015 + + + o PUTROOTFH + + o LOOKUP "this" + + o LOOKUP "is" + + o LOOKUP "the" + + o LOOKUP "path" + + o GETFH + + o GETATTR(fsid, fileid, size, time_modify) + + Under the given circumstances, the following will be the result: + + o PUTROOTFH --> NFS_OK. The current fh is now the root of the + pseudo-fs. + + o LOOKUP "this" --> NFS_OK. The current fh is for /this and is + within the pseudo-fs. + + o LOOKUP "is" --> NFS_OK. The current fh is for /this/is and is + within the pseudo-fs. + + o LOOKUP "the" --> NFS_OK. The current fh is for /this/is/the and + is within the pseudo-fs. + + o LOOKUP "path" --> NFS_OK. The current fh is for /this/is/the/path + and is within a new, absent file system, but ... the client will + never see the value of that fh. + + o GETFH --> NFS4ERR_MOVED. Fails, because the current fh is in an + absent file system at the start of the operation and the + specification makes no exception for GETFH. + + o GETATTR(fsid, fileid, size, time_modify). Not executed, because + the failure of the GETFH stops the processing of the COMPOUND. + + Given the failure of the GETFH, the client has the job of determining + the root of the absent file system and where to find that file + system, i.e., the server and path relative to that server's root fh. + Note here that in this example, the client did not obtain filehandles + and attribute information (e.g., fsid) for the intermediate + directories, so that it would not be sure where the absent file + system starts. It could be the case, for example, that /this/is/the + is the root of the moved file system and that the reason that the + lookup of "path" succeeded is that the file system was not absent on + + + +Haynes & Noveck Standards Track [Page 90] + +RFC 7530 NFSv4 March 2015 + + + that operation but was moved between the last LOOKUP and the GETFH + (since COMPOUND is not atomic). Even if we had the fsids for all of + the intermediate directories, we could have no way of knowing that + /this/is/the/path was the root of a new file system, since we don't + yet have its fsid. + + In order to get the necessary information, let us re-send the chain + of LOOKUPs with GETFHs and GETATTRs to at least get the fsids so we + can be sure where the appropriate file system boundaries are. The + client could choose to get fs_locations at the same time, but in most + cases the client will have a good guess as to where the file system + boundaries are (because of where NFS4ERR_MOVED was, and was not, + received), making the fetching of fs_locations unnecessary. + + OP01: PUTROOTFH --> NFS_OK + + - The current fh is at the root of the pseudo-fs. + + OP02: GETATTR(fsid) --> NFS_OK + + - Just for completeness. Normally, clients will know the fsid of + the pseudo-fs as soon as they establish communication with a + server. + + OP03: LOOKUP "this" --> NFS_OK + + OP04: GETATTR(fsid) --> NFS_OK + + - Get the current fsid to see where the file system boundaries are. + The fsid will be that for the pseudo-fs in this example, so no + boundary. + + OP05: GETFH --> NFS_OK + + - The current fh is for /this and is within the pseudo-fs. + + OP06: LOOKUP "is" --> NFS_OK + + - The current fh is for /this/is and is within the pseudo-fs. + + OP07: GETATTR(fsid) --> NFS_OK + + - Get the current fsid to see where the file system boundaries are. + The fsid will be that for the pseudo-fs in this example, so no + boundary. + + + + + + +Haynes & Noveck Standards Track [Page 91] + +RFC 7530 NFSv4 March 2015 + + + OP08: GETFH --> NFS_OK + + - The current fh is for /this/is and is within the pseudo-fs. + + OP09: LOOKUP "the" --> NFS_OK + + - The current fh is for /this/is/the and is within the pseudo-fs. + + OP10: GETATTR(fsid) --> NFS_OK + + - Get the current fsid to see where the file system boundaries are. + The fsid will be that for the pseudo-fs in this example, so no + boundary. + + OP11: GETFH --> NFS_OK + + - The current fh is for /this/is/the and is within the pseudo-fs. + + OP12: LOOKUP "path" --> NFS_OK + + - The current fh is for /this/is/the/path and is within a new, + absent file system, but ... + + - The client will never see the value of that fh. + + OP13: GETATTR(fsid, fs_locations) --> NFS_OK + + - We are getting the fsid to know where the file system boundaries + are. In this operation, the fsid will be different than that of + the parent directory (which in turn was retrieved in OP10). Note + that the fsid we are given will not necessarily be preserved at + the new location. That fsid might be different, and in fact the + fsid we have for this file system might be a valid fsid of a + different file system on that new server. + + - In this particular case, we are pretty sure anyway that what has + moved is /this/is/the/path rather than /this/is/the since we have + the fsid of the latter and it is that of the pseudo-fs, which + presumably cannot move. However, in other examples, we might not + have this kind of information to rely on (e.g., /this/is/the might + be a non-pseudo-file system separate from /this/is/the/path), so + we need to have other reliable source information on the boundary + of the file system that is moved. If, for example, the file + system /this/is had moved, we would have a case of migration + rather than referral, and once the boundaries of the migrated file + system were clear we could fetch fs_locations. + + + + + +Haynes & Noveck Standards Track [Page 92] + +RFC 7530 NFSv4 March 2015 + + + - We are fetching fs_locations because the fact that we got an + NFS4ERR_MOVED at this point means that this is most likely a + referral and we need the destination. Even if it is the case that + /this/is/the is a file system that has migrated, we will still + need the location information for that file system. + + OP14: GETFH --> NFS4ERR_MOVED + + - Fails because current fh is in an absent file system at the start + of the operation, and the specification makes no exception for + GETFH. Note that this means the server will never send the client + a filehandle from within an absent file system. + + Given the above, the client knows where the root of the absent file + system is (/this/is/the/path) by noting where the change of fsid + occurred (between "the" and "path"). The fs_locations attribute also + gives the client the actual location of the absent file system so + that the referral can proceed. The server gives the client the bare + minimum of information about the absent file system so that there + will be very little scope for problems of conflict between + information sent by the referring server and information of the file + system's home. No filehandles and very few attributes are present on + the referring server, and the client can treat those it receives as + transient information with the function of enabling the referral. + +8.7.2. Referral Example (READDIR) + + Another context in which a client may encounter referrals is when it + does a READDIR on a directory in which some of the subdirectories are + the roots of absent file systems. + + Suppose such a directory is read as follows: + + o PUTROOTFH + + o LOOKUP "this" + + o LOOKUP "is" + + o LOOKUP "the" + + o READDIR(fsid, size, time_modify, mounted_on_fileid) + + + + + + + + + +Haynes & Noveck Standards Track [Page 93] + +RFC 7530 NFSv4 March 2015 + + + In this case, because rdattr_error is not requested, fs_locations is + not requested, and some of the attributes cannot be provided, the + result will be an NFS4ERR_MOVED error on the READDIR, with the + detailed results as follows: + + o PUTROOTFH --> NFS_OK. The current fh is at the root of the + pseudo-fs. + + o LOOKUP "this" --> NFS_OK. The current fh is for /this and is + within the pseudo-fs. + + o LOOKUP "is" --> NFS_OK. The current fh is for /this/is and is + within the pseudo-fs. + + o LOOKUP "the" --> NFS_OK. The current fh is for /this/is/the and + is within the pseudo-fs. + + o READDIR(fsid, size, time_modify, mounted_on_fileid) --> + NFS4ERR_MOVED. Note that the same error would have been returned + if /this/is/the had migrated, but it is returned because the + directory contains the root of an absent file system. + + So now suppose that we re-send with rdattr_error: + + o PUTROOTFH + + o LOOKUP "this" + + o LOOKUP "is" + + o LOOKUP "the" + + o READDIR(rdattr_error, fsid, size, time_modify, mounted_on_fileid) + + The results will be: + + o PUTROOTFH --> NFS_OK. The current fh is at the root of the + pseudo-fs. + + o LOOKUP "this" --> NFS_OK. The current fh is for /this and is + within the pseudo-fs. + + o LOOKUP "is" --> NFS_OK. The current fh is for /this/is and is + within the pseudo-fs. + + o LOOKUP "the" --> NFS_OK. The current fh is for /this/is/the and + is within the pseudo-fs. + + + + +Haynes & Noveck Standards Track [Page 94] + +RFC 7530 NFSv4 March 2015 + + + o READDIR(rdattr_error, fsid, size, time_modify, mounted_on_fileid) + --> NFS_OK. The attributes for the directory entry with the + component named "path" will only contain rdattr_error with the + value NFS4ERR_MOVED, together with an fsid value and a value for + mounted_on_fileid. + + So suppose we do another READDIR to get fs_locations (although we + could have used a GETATTR directly, as in Section 8.7.1): + + o PUTROOTFH + + o LOOKUP "this" + + o LOOKUP "is" + + o LOOKUP "the" + + o READDIR(rdattr_error, fs_locations, mounted_on_fileid, fsid, size, + time_modify) + + The results would be: + + o PUTROOTFH --> NFS_OK. The current fh is at the root of the + pseudo-fs. + + o LOOKUP "this" --> NFS_OK. The current fh is for /this and is + within the pseudo-fs. + + o LOOKUP "is" --> NFS_OK. The current fh is for /this/is and is + within the pseudo-fs. + + o LOOKUP "the" --> NFS_OK. The current fh is for /this/is/the and + is within the pseudo-fs. + + o READDIR(rdattr_error, fs_locations, mounted_on_fileid, fsid, size, + time_modify) --> NFS_OK. The attributes will be as shown below. + + The attributes for the directory entry with the component named + "path" will only contain: + + o rdattr_error (value: NFS_OK) + + o fs_locations + + o mounted_on_fileid (value: unique fileid within referring file + system) + + o fsid (value: unique value within referring server) + + + +Haynes & Noveck Standards Track [Page 95] + +RFC 7530 NFSv4 March 2015 + + + The attributes for entry "path" will not contain size or time_modify, + because these attributes are not available within an absent file + system. + +8.8. The Attribute fs_locations + + The fs_locations attribute is defined by both fs_location4 + (Section 2.2.6) and fs_locations4 (Section 2.2.7). It is used to + represent the location of a file system by providing a server name + and the path to the root of the file system within that server's + namespace. When a set of servers have corresponding file systems at + the same path within their namespaces, an array of server names may + be provided. An entry in the server array is a UTF-8 string and + represents one of a traditional DNS host name, IPv4 address, IPv6 + address, or a zero-length string. A zero-length string SHOULD be + used to indicate the current address being used for the RPC. It is + not a requirement that all servers that share the same rootpath be + listed in one fs_location4 instance. The array of server names is + provided for convenience. Servers that share the same rootpath may + also be listed in separate fs_location4 entries in the fs_locations + attribute. + + The fs_locations4 data type and fs_locations attribute contain an + array of such locations. Since the namespace of each server may be + constructed differently, the fs_root field is provided. The path + represented by the fs_root represents the location of the file system + in the current server's namespace, i.e., that of the server from + which the fs_locations attribute was obtained. The fs_root path is + meant to aid the client by clearly referencing the root of the file + system whose locations are being reported, no matter what object + within the current file system the current filehandle designates. + The fs_root is simply the pathname the client used to reach the + object on the current server (i.e., the object to which the + fs_locations attribute applies). + + When the fs_locations attribute is interrogated and there are no + alternative file system locations, the server SHOULD return a + zero-length array of fs_location4 structures, together with a + valid fs_root. + + As an example, suppose there is a replicated file system located at + two servers (servA and servB). At servA, the file system is located + at path /a/b/c. At servB, the file system is located at path /x/y/z. + If the client were to obtain the fs_locations value for the directory + at /a/b/c/d, it might not necessarily know that the file system's + root is located in servA's namespace at /a/b/c. When the client + switches to servB, it will need to determine that the directory it + first referenced at servA is now represented by the path /x/y/z/d + + + +Haynes & Noveck Standards Track [Page 96] + +RFC 7530 NFSv4 March 2015 + + + on servB. To facilitate this, the fs_locations attribute provided by + servA would have an fs_root value of /a/b/c and two entries in + fs_locations. One entry in fs_locations will be for itself (servA), + and the other will be for servB with a path of /x/y/z. With this + information, the client is able to substitute /x/y/z for /a/b/c at + the beginning of its access path and construct /x/y/z/d to use for + the new server. + + Note that there is no requirement that the number of components in + each rootpath be the same; there is no relation between the number of + components in the rootpath or fs_root, and none of the components in + each rootpath and fs_root have to be the same. In the above example, + we could have had a third element in the locations array, with server + equal to "servC" and rootpath equal to "/I/II", and a fourth element + in the locations array, with server equal to "servD" and rootpath + equal to "/aleph/beth/gimel/daleth/he". + + The relationship between an fs_root and a rootpath is that the client + replaces the pathname indicated in the fs_root for the current server + for the substitute indicated in the rootpath for the new server. + + For an example of a referred or migrated file system, suppose there + is a file system located at serv1. At serv1, the file system is + located at /az/buky/vedi/glagoli. The client finds that the object + at glagoli has migrated (or is a referral). The client gets the + fs_locations attribute, which contains an fs_root of /az/buky/vedi/ + glagoli, and one element in the locations array, with server equal to + serv2, and rootpath equal to /izhitsa/fita. The client replaces + /az/buky/vedi/glagoli with /izhitsa/fita and uses the latter pathname + on serv2. + + Thus, the server MUST return an fs_root that is equal to the path the + client used to reach the object to which the fs_locations attribute + applies. Otherwise, the client cannot determine the new path to use + on the new server. + + + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 97] + +RFC 7530 NFSv4 March 2015 + + +9. File Locking and Share Reservations + + Integrating locking into the NFS protocol necessarily causes it to be + stateful. With the inclusion of share reservations, the protocol + becomes substantially more dependent on state than the traditional + combination of NFS and NLM (Network Lock Manager) [xnfs]. There are + three components to making this state manageable: + + o clear division between client and server + + o ability to reliably detect inconsistency in state between client + and server + + o simple and robust recovery mechanisms + + In this model, the server owns the state information. The client + requests changes in locks, and the server responds with the changes + made. Non-client-initiated changes in locking state are infrequent. + The client receives prompt notification of such changes and can + adjust its view of the locking state to reflect the server's changes. + + Individual pieces of state created by the server and passed to the + client at its request are represented by 128-bit stateids. These + stateids may represent a particular open file, a set of byte-range + locks held by a particular owner, or a recallable delegation of + privileges to access a file in particular ways or at a particular + location. + + In all cases, there is a transition from the most general information + that represents a client as a whole to the eventual lightweight + stateid used for most client and server locking interactions. The + details of this transition will vary with the type of object, but it + always starts with a client ID. + + To support Win32 share reservations, it is necessary to atomically + OPEN or CREATE files and apply the appropriate locks in the same + operation. Having a separate share/unshare operation would not allow + correct implementation of the Win32 OpenFile API. In order to + correctly implement share semantics, the previous NFS protocol + mechanisms used when a file is opened or created (LOOKUP, CREATE, + ACCESS) need to be replaced. The NFSv4 protocol has an OPEN + operation that subsumes the NFSv3 methodology of LOOKUP, CREATE, and + ACCESS. However, because many operations require a filehandle, the + traditional LOOKUP is preserved to map a filename to a filehandle + without establishing state on the server. The policy of granting + access or modifying files is managed by the server based on the + client's state. These mechanisms can implement policy ranging from + advisory only locking to full mandatory locking. + + + +Haynes & Noveck Standards Track [Page 98] + +RFC 7530 NFSv4 March 2015 + + +9.1. Opens and Byte-Range Locks + + It is assumed that manipulating a byte-range lock is rare when + compared to READ and WRITE operations. It is also assumed that + server restarts and network partitions are relatively rare. + Therefore, it is important that the READ and WRITE operations have a + lightweight mechanism to indicate if they possess a held lock. A + byte-range lock request contains the heavyweight information required + to establish a lock and uniquely define the owner of the lock. + + The following sections describe the transition from the heavyweight + information to the eventual stateid used for most client and server + locking and lease interactions. + +9.1.1. Client ID + + For each LOCK request, the client must identify itself to the server. + This is done in such a way as to allow for correct lock + identification and crash recovery. A sequence of a SETCLIENTID + operation followed by a SETCLIENTID_CONFIRM operation is required to + establish the identification onto the server. Establishment of + identification by a new incarnation of the client also has the effect + of immediately breaking any leased state that a previous incarnation + of the client might have had on the server, as opposed to forcing the + new client incarnation to wait for the leases to expire. Breaking + the lease state amounts to the server removing all lock, share + reservation, and, where the server is not supporting the + CLAIM_DELEGATE_PREV claim type, all delegation state associated with + the same client with the same identity. For a discussion of + delegation state recovery, see Section 10.2.1. + + Owners of opens and owners of byte-range locks are separate entities + and remain separate even if the same opaque arrays are used to + designate owners of each. The protocol distinguishes between + open-owners (represented by open_owner4 structures) and lock-owners + (represented by lock_owner4 structures). + + Both sorts of owners consist of a clientid and an opaque owner + string. For each client, the set of distinct owner values used with + that client constitutes the set of owners of that type, for the given + client. + + 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 latter being the open-owner associated with the open file under + which the LOCK operation was done. + + + + + +Haynes & Noveck Standards Track [Page 99] + +RFC 7530 NFSv4 March 2015 + + + Client identification is encapsulated in the following structure: + + struct nfs_client_id4 { + verifier4 verifier; + opaque id; + }; + + The first field, verifier, is a client incarnation verifier that is + used to detect client reboots. Only if the verifier is different + from that which the server has previously recorded for the client (as + identified by the second field of the structure, id) does the server + start the process of canceling the client's leased state. + + The second field, id, is a variable-length string that uniquely + defines the client. + + There are several considerations for how the client generates the id + string: + + o The string should be unique so that multiple clients do not + present the same string. The consequences of two clients + presenting the same string range from one client getting an error + to one client having its leased state abruptly and unexpectedly + canceled. + + o The string should be selected so the subsequent incarnations + (e.g., reboots) of the same client cause the client to present the + same string. The implementer is cautioned against an approach + that requires the string to be recorded in a local file because + this precludes the use of the implementation in an environment + where there is no local disk and all file access is from an NFSv4 + server. + + o The string should be different for each server network address + that the client accesses, rather than common to all server network + addresses. The reason is that it may not be possible for the + client to tell if the same server is listening on multiple network + addresses. If the client issues SETCLIENTID with the same id + string to each network address of such a server, the server will + think it is the same client, and each successive SETCLIENTID will + cause the server to begin the process of removing the client's + previous leased state. + + o The algorithm for generating the string should not assume that the + client's network address won't change. This includes changes + between client incarnations and even changes while the client is + still running in its current incarnation. This means that if the + client includes just the client's and server's network address in + + + +Haynes & Noveck Standards Track [Page 100] + +RFC 7530 NFSv4 March 2015 + + + the id string, there is a real risk, after the client gives up the + network address, that another client, using a similar algorithm + for generating the id string, will generate a conflicting id + string. + + Given the above considerations, an example of a well-generated id + string is one that includes: + + o The server's network address. + + o The client's network address. + + o For a user-level NFSv4 client, it should contain additional + information to distinguish the client from other user-level + clients running on the same host, such as a universally unique + identifier (UUID). + + o Additional information that tends to be unique, such as one or + more of: + + * The client machine's serial number (for privacy reasons, it is + best to perform some one-way function on the serial number). + + * A MAC address (for privacy reasons, it is best to perform some + one-way function on the MAC address). + + * The timestamp of when the NFSv4 software was first installed on + the client (though this is subject to the previously mentioned + caution about using information that is stored in a file, + because the file might only be accessible over NFSv4). + + * A true random number. However, since this number ought to be + the same between client incarnations, this shares the same + problem as that of using the timestamp of the software + installation. + + As a security measure, the server MUST NOT cancel a client's leased + state if the principal that established the state for a given id + string is not the same as the principal issuing the SETCLIENTID. + + Note that SETCLIENTID (Section 16.33) and SETCLIENTID_CONFIRM + (Section 16.34) have a secondary purpose of establishing the + information the server needs to make callbacks to the client for the + purpose of supporting delegations. It is permitted to change this + information via SETCLIENTID and SETCLIENTID_CONFIRM within the same + incarnation of the client without removing the client's leased state. + + + + + +Haynes & Noveck Standards Track [Page 101] + +RFC 7530 NFSv4 March 2015 + + + Once a SETCLIENTID and SETCLIENTID_CONFIRM sequence has successfully + completed, the client uses the shorthand client identifier, of type + clientid4, instead of the longer and less compact nfs_client_id4 + structure. This shorthand client identifier (a client ID) is + assigned by the server and should be chosen so that it will not + conflict with a client ID previously assigned by the server. This + applies across server restarts or reboots. When a client ID is + presented to a server and that client ID is not recognized, as would + happen after a server reboot, the server will reject the request with + the error NFS4ERR_STALE_CLIENTID. When this happens, the client must + obtain a new client ID by use of the SETCLIENTID operation and then + proceed to any other necessary recovery for the server reboot case + (see Section 9.6.2). + + The client must also employ the SETCLIENTID operation when it + receives an NFS4ERR_STALE_STATEID error using a stateid derived from + its current client ID, since this also indicates a server reboot, + which has invalidated the existing client ID (see Section 9.6.2 for + details). + + See the detailed descriptions of SETCLIENTID (Section 16.33.4) and + SETCLIENTID_CONFIRM (Section 16.34.4) for a complete specification of + the operations. + +9.1.2. Server Release of Client ID + + If the server determines that the client holds no associated state + for its client ID, the server may choose to release the client ID. + The server may make this choice for an inactive client so that + resources are not consumed by those intermittently active clients. + If the client contacts the server after this release, the server must + ensure that the client receives the appropriate error so that it will + use the SETCLIENTID/SETCLIENTID_CONFIRM sequence to establish a new + identity. It should be clear that the server must be very hesitant + to release a client ID since the resulting work on the client to + recover from such an event will be the same burden as if the server + had failed and restarted. Typically, a server would not release a + client ID unless there had been no activity from that client for many + minutes. + + Note that if the id string in a SETCLIENTID request is properly + constructed, and if the client takes care to use the same principal + for each successive use of SETCLIENTID, then, barring an active + denial-of-service attack, NFS4ERR_CLID_INUSE should never be + returned. + + + + + + +Haynes & Noveck Standards Track [Page 102] + +RFC 7530 NFSv4 March 2015 + + + However, client bugs, server bugs, or perhaps a deliberate change of + the principal owner of the id string (such as the case of a client + that changes security flavors, and under the new flavor there is no + mapping to the previous owner) will in rare cases result in + NFS4ERR_CLID_INUSE. + + In that event, when the server gets a SETCLIENTID for a client ID + that currently has no state, or it has state but the lease has + expired, rather than returning NFS4ERR_CLID_INUSE, the server MUST + allow the SETCLIENTID and confirm the new client ID if followed by + the appropriate SETCLIENTID_CONFIRM. + +9.1.3. Use of Seqids + + In several contexts, 32-bit sequence values called "seqids" are used + as part of managing locking state. Such values are used: + + o To provide an ordering of locking-related operations associated + with a particular lock-owner or open-owner. See Section 9.1.7 for + a detailed explanation. + + o To define an ordered set of instances of a set of locks sharing a + particular set of ownership characteristics. See Section 9.1.4.2 + for a detailed explanation. + + Successive seqid values for the same object are normally arrived at + by incrementing the current value by one. This pattern continues + until the seqid is incremented past NFS4_UINT32_MAX, in which case + one (rather than zero) is to be the next seqid value. + + When two seqid values are to be compared to determine which of the + two is later, the possibility of wraparound needs to be considered. + In many cases, the values are such that simple numeric comparisons + can be used. For example, if the seqid values to be compared are + both less than one million, the higher value can be considered the + later. On the other hand, if one of the values is at or near + NFS_UINT32_MAX and the other is less than one million, then + implementations can reasonably decide that the lower value has had + one more wraparound and is thus, while numerically lower, actually + later. + + Implementations can compare seqids in the presence of potential + wraparound by adopting the reasonable assumption that the chain of + increments from one to the other is shorter than 2**31. So, if the + difference between the two seqids is less than 2**31, then the lower + seqid is to be treated as earlier. If, however, the difference + + + + + +Haynes & Noveck Standards Track [Page 103] + +RFC 7530 NFSv4 March 2015 + + + between the two seqids is greater than or equal to 2**31, then it can + be assumed that the lower seqid has encountered one more wraparound + and can be treated as later. + +9.1.4. Stateid Definition + + When the server grants a lock of any type (including opens, + byte-range locks, and delegations), it responds with a unique stateid + that represents a set of locks (often a single lock) for the same + file, of the same type, and sharing the same ownership + characteristics. Thus, opens of the same file by different + open-owners each have an identifying stateid. Similarly, each set of + byte-range locks on a file owned by a specific lock-owner has its own + identifying stateid. Delegations also have associated stateids by + which they may be referenced. The stateid is used as a shorthand + reference to a lock or set of locks, and given a stateid, the server + can determine the associated state-owner or state-owners (in the case + of an open-owner/lock-owner pair) and the associated filehandle. + When stateids are used, the current filehandle must be the one + associated with that stateid. + + All stateids associated with a given client ID are associated with a + common lease that represents the claim of those stateids and the + objects they represent to be maintained by the server. See + Section 9.5 for a discussion of the lease. + + Each stateid must be unique to the server. Many operations take a + stateid as an argument but not a clientid, so the server must be able + to infer the client from the stateid. + +9.1.4.1. Stateid Types + + With the exception of special stateids (see Section 9.1.4.3), each + stateid represents locking objects of one of a set of types defined + by the NFSv4 protocol. Note that in all these cases, where we speak + of a guarantee, it is understood there are situations such as a + client restart, or lock revocation, that allow the guarantee to be + voided. + + o Stateids may represent opens of files. + + Each stateid in this case represents the OPEN state for a given + client ID/open-owner/filehandle triple. Such stateids are subject + to change (with consequent incrementing of the stateid's seqid) in + response to OPENs that result in upgrade and OPEN_DOWNGRADE + operations. + + + + + +Haynes & Noveck Standards Track [Page 104] + +RFC 7530 NFSv4 March 2015 + + + o Stateids may represent sets of byte-range locks. + + All locks held on a particular file by a particular owner and all + gotten under the aegis of a particular open file are associated + with a single stateid, with the seqid being incremented whenever + LOCK and LOCKU operations affect that set of locks. + + o Stateids may represent file delegations, which are recallable + guarantees by the server to the client that other clients will not + reference, or will not modify, a particular file until the + delegation is returned. + + A stateid represents a single delegation held by a client for a + particular filehandle. + +9.1.4.2. Stateid Structure + + Stateids are divided into two fields: a 96-bit "other" field + identifying the specific set of locks and a 32-bit "seqid" sequence + value. Except in the case of special stateids (see Section 9.1.4.3), + a particular value of the "other" field denotes a set of locks of the + same type (for example, byte-range locks, opens, or delegations), for + a specific file or directory, and sharing the same ownership + characteristics. The seqid designates a specific instance of such a + set of locks, and is incremented to indicate changes in such a set of + locks, by either the addition or deletion of locks from the set, a + change in the byte-range they apply to, or an upgrade or downgrade in + the type of one or more locks. + + When such a set of locks is first created, the server returns a + stateid with a seqid value of one. On subsequent operations that + modify the set of locks, the server is required to advance the + seqid field by one whenever it returns a stateid for the same + state-owner/file/type combination and the operation is one that might + make some change in the set of locks actually designated. In this + case, the server will return a stateid with an "other" field the same + as previously used for that state-owner/file/type combination, with + an incremented seqid field. + + Seqids will be compared, by both the client and the server. The + client uses such comparisons to determine the order of operations, + while the server uses them to determine whether the + NFS4ERR_OLD_STATEID error is to be returned. In all cases, the + possibility of seqid wraparound needs to be taken into account, as + discussed in Section 9.1.3. + + + + + + +Haynes & Noveck Standards Track [Page 105] + +RFC 7530 NFSv4 March 2015 + + +9.1.4.3. Special Stateids + + Stateid values whose "other" field is either all zeros or all ones + are reserved. They MUST NOT be assigned by the server but have + special meanings defined by the protocol. The particular meaning + depends on whether the "other" field is all zeros or all ones and the + specific value of the seqid field. + + The following combinations of "other" and seqid are defined in NFSv4: + + Anonymous Stateid: When "other" and seqid are both zero, the stateid + is treated as a special anonymous stateid, which can be used in + READ, WRITE, and SETATTR requests to indicate the absence of any + open state associated with the request. When an anonymous stateid + value is used, and an existing open denies the form of access + requested, then access will be denied to the request. + + READ Bypass Stateid: When "other" and seqid are both all ones, the + stateid is a special READ bypass stateid. When this value is used + in WRITE or SETATTR, it is treated like the anonymous value. When + used in READ, the server MAY grant access, even if access would + normally be denied to READ requests. + + If a stateid value is used that has all zeros or all ones in the + "other" field but does not match one of the cases above, the server + MUST return the error NFS4ERR_BAD_STATEID. + + Special stateids, unlike other stateids, are not associated with + individual client IDs or filehandles and can be used with all valid + client IDs and filehandles. + +9.1.4.4. Stateid Lifetime and Validation + + Stateids must remain valid until either a client restart or a server + restart, or until the client returns all of the locks associated with + the stateid by means of an operation such as CLOSE or DELEGRETURN. + If the locks are lost due to revocation, as long as the client ID is + valid, the stateid remains a valid designation of that revoked state. + Stateids associated with byte-range locks are an exception. They + remain valid even if a LOCKU frees all remaining locks, so long as + the open file with which they are associated remains open. + + It should be noted that there are situations in which the client's + locks become invalid, without the client requesting they be returned. + These include lease expiration and a number of forms of lock + revocation within the lease period. It is important to note that in + these situations, the stateid remains valid and the client can use it + to determine the disposition of the associated lost locks. + + + +Haynes & Noveck Standards Track [Page 106] + +RFC 7530 NFSv4 March 2015 + + + An "other" value must never be reused for a different purpose (i.e., + different filehandle, owner, or type of locks) within the context of + a single client ID. A server may retain the "other" value for the + same purpose beyond the point where it may otherwise be freed, but if + it does so, it must maintain seqid continuity with previous values. + + One mechanism that may be used to satisfy the requirement that the + server recognize invalid and out-of-date stateids is for the server + to divide the "other" field of the stateid into two fields: + + o An index into a table of locking-state structures. + + o A generation number that is incremented on each allocation of a + table entry for a particular use. + + And then store the following in each table entry: + + o The client ID with which the stateid is associated. + + o The current generation number for the (at most one) valid stateid + sharing this index value. + + o The filehandle of the file on which the locks are taken. + + o An indication of the type of stateid (open, byte-range lock, file + delegation). + + o The last seqid value returned corresponding to the current "other" + value. + + o An indication of the current status of the locks associated with + this stateid -- in particular, whether these have been revoked + and, if so, for what reason. + + With this information, an incoming stateid can be validated and the + appropriate error returned when necessary. Special and non-special + stateids are handled separately. (See Section 9.1.4.3 for a + discussion of special stateids.) + + When a stateid is being tested, and the "other" field is all zeros or + all ones, a check that the "other" and seqid fields match a defined + combination for a special stateid is done and the results determined + as follows: + + o If the "other" and seqid fields do not match a defined combination + associated with a special stateid, the error NFS4ERR_BAD_STATEID + is returned. + + + + +Haynes & Noveck Standards Track [Page 107] + +RFC 7530 NFSv4 March 2015 + + + o If the combination is valid in general but is not appropriate to + the context in which the stateid is used (e.g., an all-zero + stateid is used when an open stateid is required in a LOCK + operation), the error NFS4ERR_BAD_STATEID is also returned. + + o Otherwise, the check is completed and the special stateid is + accepted as valid. + + When a stateid is being tested, and the "other" field is neither all + zeros nor all ones, the following procedure could be used to validate + an incoming stateid and return an appropriate error, when necessary, + assuming that the "other" field would be divided into a table index + and an entry generation. Note that the terms "earlier" and "later" + used in connection with seqid comparison are to be understood as + explained in Section 9.1.3. + + o If the table index field is outside the range of the associated + table, return NFS4ERR_BAD_STATEID. + + o If the selected table entry is of a different generation than that + specified in the incoming stateid, return NFS4ERR_BAD_STATEID. + + o If the selected table entry does not match the current filehandle, + return NFS4ERR_BAD_STATEID. + + o If the stateid represents revoked state or state lost as a result + of lease expiration, then return NFS4ERR_EXPIRED, + NFS4ERR_BAD_STATEID, or NFS4ERR_ADMIN_REVOKED, as appropriate. + + o If the stateid type is not valid for the context in which the + stateid appears, return NFS4ERR_BAD_STATEID. Note that a stateid + may be valid in general but invalid for a particular operation, + as, for example, when a stateid that doesn't represent byte-range + locks is passed to the non-from_open case of LOCK or to LOCKU, or + when a stateid that does not represent an open is passed to CLOSE + or OPEN_DOWNGRADE. In such cases, the server MUST return + NFS4ERR_BAD_STATEID. + + o If the seqid field is not zero and it is later than the current + sequence value corresponding to the current "other" field, return + NFS4ERR_BAD_STATEID. + + o If the seqid field is earlier than the current sequence value + corresponding to the current "other" field, return + NFS4ERR_OLD_STATEID. + + + + + + +Haynes & Noveck Standards Track [Page 108] + +RFC 7530 NFSv4 March 2015 + + + o Otherwise, the stateid is valid, and the table entry should + contain any additional information about the type of stateid and + information associated with that particular type of stateid, such + as the associated set of locks (e.g., open-owner and lock-owner + information), as well as information on the specific locks + themselves, such as open modes and byte ranges. + +9.1.4.5. Stateid Use for I/O Operations + + Clients performing Input/Output (I/O) operations need to select an + appropriate stateid based on the locks (including opens and + delegations) held by the client and the various types of state-owners + sending the I/O requests. SETATTR operations that change the file + size are treated like I/O operations in this regard. + + The following rules, applied in order of decreasing priority, govern + the selection of the appropriate stateid. In following these rules, + the client will only consider locks of which it has actually received + notification by an appropriate operation response or callback. + + o If the client holds a delegation for the file in question, the + delegation stateid SHOULD be used. + + o Otherwise, if the entity corresponding to the lock-owner (e.g., a + process) sending the I/O has a byte-range lock stateid for the + associated open file, then the byte-range lock stateid for that + lock-owner and open file SHOULD be used. + + o If there is no byte-range lock stateid, then the OPEN stateid for + the current open-owner, i.e., the OPEN stateid for the open file + in question, SHOULD be used. + + o Finally, if none of the above apply, then a special stateid SHOULD + be used. + + Ignoring these rules may result in situations in which the server + does not have information necessary to properly process the request. + For example, when mandatory byte-range locks are in effect, if the + stateid does not indicate the proper lock-owner, via a lock stateid, + a request might be avoidably rejected. + + The server, however, should not try to enforce these ordering rules + and should use whatever information is available to properly process + I/O requests. In particular, when a client has a delegation for a + given file, it SHOULD take note of this fact in processing a request, + even if it is sent with a special stateid. + + + + + +Haynes & Noveck Standards Track [Page 109] + +RFC 7530 NFSv4 March 2015 + + +9.1.4.6. Stateid Use for SETATTR Operations + + 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 + special stateid or, when a delegation is held for the file in + question, a delegation stateid. While the server SHOULD validate the + stateid and may use the stateid to optimize the determination as to + whether a delegation is held, it SHOULD note the presence of a + delegation even when a special stateid is sent, and MUST accept a + valid delegation stateid when sent. + +9.1.5. Lock-Owner + + When requesting a lock, the client must present to the server the + client ID and an identifier for the owner of the requested lock. + These two fields comprise the lock-owner and are defined as follows: + + o A client ID returned by the server as part of the client's use of + the SETCLIENTID operation. + + o A variable-length opaque array used to uniquely define the owner + of a lock managed by the client. + + This may be a thread id, process id, or other unique value. + + 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 server will be maintaining the correspondence between them. + +9.1.6. Use of the Stateid and Locking + + All READ, WRITE, and SETATTR operations contain a stateid. For the + purposes of this section, SETATTR operations that change the size + 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 + the file by means of the SETATTR), even where SETATTR is not + explicitly mentioned in the text. The stateid passed to one of these + operations must be one that represents an OPEN (e.g., via the + open-owner), a set of byte-range locks, or a delegation, or it may be + a special stateid representing anonymous access or the READ bypass + stateid. + + If the state-owner performs a READ or WRITE in a situation in which + it has established a lock or share reservation on the server (any + OPEN constitutes a share reservation), the stateid (previously + returned by the server) must be used to indicate what locks, + including both byte-range locks and share reservations, are held by + the state-owner. If no state is established by the client -- either + + + +Haynes & Noveck Standards Track [Page 110] + +RFC 7530 NFSv4 March 2015 + + + byte-range lock or share reservation -- the anonymous stateid is + used. Regardless of whether an anonymous stateid or a stateid + returned by the server is used, 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 WRITE operation. + + Share reservations are established by OPEN operations and by their + nature are mandatory in that when the OPEN denies READ or WRITE + operations, that denial results in such operations being rejected + with error NFS4ERR_LOCKED. Byte-range locks may be implemented by + the server as either mandatory or advisory, or the choice of + mandatory or advisory behavior may be determined by the server on the + basis of the file being accessed (for example, some UNIX-based + servers support a "mandatory lock bit" on the mode attribute such + that if set, byte-range locks are required on the file before I/O is + possible). When byte-range locks are advisory, they only prevent the + granting of conflicting lock requests and have no effect on READs or + WRITEs. Mandatory byte-range locks, however, prevent conflicting I/O + operations. When they are attempted, they are rejected with + NFS4ERR_LOCKED. When the client gets NFS4ERR_LOCKED on a file it + knows it has the proper share reservation for, it will need to issue + a LOCK request on the region of the file that includes the region the + I/O was to be performed on, with an appropriate locktype (i.e., + READ*_LT for a READ operation, WRITE*_LT for a WRITE operation). + + With NFSv3, there was no notion of a stateid, so there was no way to + tell if the application process of the client sending the READ or + WRITE operation had also acquired the appropriate byte-range lock on + the file. Thus, there was no way to implement mandatory locking. + With the stateid construct, this barrier has been removed. + + Note that for UNIX environments that support mandatory file locking, + the distinction between advisory and mandatory locking is subtle. In + fact, advisory and mandatory byte-range locks are exactly the same + insofar as the APIs and requirements on implementation are concerned. + If the mandatory lock attribute is set on the file, the server checks + to see if the lock-owner has an appropriate shared (read) or + exclusive (write) byte-range lock on the region it wishes to read or + write to. If there is no appropriate lock, the server checks if + there is a conflicting lock (which can be done by attempting to + acquire the conflicting lock on behalf of the lock-owner and, if + successful, release the lock after the READ or WRITE is done), and if + there is, the server returns NFS4ERR_LOCKED. + + For Windows environments, there are no advisory byte-range locks, so + the server always checks for byte-range locks during I/O requests. + + + + + +Haynes & Noveck Standards Track [Page 111] + +RFC 7530 NFSv4 March 2015 + + + Thus, the NFSv4 LOCK operation does not need to distinguish between + advisory and mandatory byte-range locks. It is the NFSv4 server's + processing of the READ and WRITE operations that introduces the + distinction. + + Every stateid other than the special stateid values noted in this + section, whether returned by an OPEN-type operation (i.e., OPEN, + OPEN_DOWNGRADE) or by a LOCK-type operation (i.e., LOCK or LOCKU), + defines an access mode for the file (i.e., READ, WRITE, or + READ-WRITE) as established by the original OPEN that began the + stateid sequence, and as modified by subsequent OPENs and + OPEN_DOWNGRADEs within that stateid sequence. When a READ, WRITE, or + SETATTR that specifies the size attribute is done, the operation is + subject to checking against the access mode to verify that the + operation is appropriate given the OPEN with which the operation is + associated. + + In the case of WRITE-type operations (i.e., WRITEs and SETATTRs that + set size), the server must verify that the access mode allows writing + and return an NFS4ERR_OPENMODE error if it does not. In the case of + READ, the server may perform the corresponding check on the access + mode, or it may choose to allow READ on opens for WRITE only, to + accommodate clients whose write implementation may unavoidably do + reads (e.g., due to buffer cache constraints). However, even if + READs are allowed in these circumstances, the server MUST still check + for locks that conflict with the READ (e.g., another open specifying + denial of READs). Note that a server that does enforce the access + mode check on READs need not explicitly check for conflicting share + reservations since the existence of OPEN for read access guarantees + that no conflicting share reservation can exist. + + A READ bypass stateid MAY allow READ operations to bypass locking + checks at the server. However, WRITE operations with a READ bypass + stateid MUST NOT bypass locking checks and are treated exactly the + same as if an anonymous stateid were used. + + A lock may not be granted while a READ or WRITE operation using one + of the special stateids is being performed and the range of the lock + request conflicts with the range of the READ or WRITE operation. For + the purposes of this paragraph, a conflict occurs when a shared lock + is requested and a WRITE operation is being performed, or an + exclusive lock is requested and either a READ or a WRITE operation is + being performed. A SETATTR that sets size is treated similarly to a + WRITE as discussed above. + + + + + + + +Haynes & Noveck Standards Track [Page 112] + +RFC 7530 NFSv4 March 2015 + + +9.1.7. Sequencing of Lock Requests + + Locking is different than most NFS operations as it requires + "at-most-one" semantics that are not provided by ONC RPC. ONC RPC + over a reliable transport is not sufficient because a sequence of + locking requests may span multiple TCP connections. In the face of + retransmission or reordering, lock or unlock requests must have a + well-defined and consistent behavior. To accomplish this, each lock + request contains a sequence number that is a consecutively increasing + integer. Different state-owners have different sequences. The + server maintains the last sequence number (L) received and the + response that was returned. The server SHOULD assign a seqid value + of one for the first request issued for any given state-owner. + Subsequent values are arrived at by incrementing the seqid value, + subject to wraparound as described in Section 9.1.3. + + Note that for requests that contain a sequence number, for each + state-owner, there should be no more than one outstanding request. + + When a request is received, its sequence number (r) is compared to + that of the last one received (L). Only if it has the correct next + sequence, normally L + 1, is the request processed beyond the point + of seqid checking. Given a properly functioning client, the response + to (r) must have been received before the last request (L) was sent. + If a duplicate of last request (r == L) is received, the stored + response is returned. If the sequence value received is any other + value, it is rejected with the return of error NFS4ERR_BAD_SEQID. + Sequence history is reinitialized whenever the SETCLIENTID/ + SETCLIENTID_CONFIRM sequence changes the client verifier. + + It is critical that the server maintain the last response sent to the + client to provide a more reliable cache of duplicate non-idempotent + requests than that of the traditional cache described in [Chet]. The + traditional duplicate request cache uses a least recently used + algorithm for removing unneeded requests. However, the last lock + request and response on a given state-owner must be cached as long as + the lock state exists on the server. + + The client MUST advance the sequence number for the CLOSE, LOCK, + LOCKU, OPEN, OPEN_CONFIRM, and OPEN_DOWNGRADE operations. This is + true even in the event that the previous operation that used the + sequence number received an error. The only exception to this rule + is if the previous operation received one of the following errors: + NFS4ERR_STALE_CLIENTID, NFS4ERR_STALE_STATEID, NFS4ERR_BAD_STATEID, + NFS4ERR_BAD_SEQID, NFS4ERR_BADXDR, NFS4ERR_RESOURCE, + NFS4ERR_NOFILEHANDLE, or NFS4ERR_MOVED. + + + + + +Haynes & Noveck Standards Track [Page 113] + +RFC 7530 NFSv4 March 2015 + + +9.1.8. Recovery from Replayed Requests + + As described above, the sequence number is per state-owner. As long + as the server maintains the last sequence number received and follows + the methods described above, there are no risks of a Byzantine router + re-sending old requests. The server need only maintain the + (state-owner, sequence number) state as long as there are open files + or closed files with locks outstanding. + + LOCK, LOCKU, OPEN, OPEN_DOWNGRADE, and CLOSE each contain a sequence + number, and therefore the risk of the replay of these operations + resulting in undesired effects is non-existent while the server + maintains the state-owner state. + +9.1.9. Interactions of Multiple Sequence Values + + Some operations may have multiple sources of data for request + sequence checking and retransmission determination. Some operations + have multiple sequence values associated with multiple types of + state-owners. In addition, such operations may also have a stateid + with its own seqid value, that will be checked for validity. + + As noted above, there may be multiple sequence values to check. The + following rules should be followed by the server in processing these + multiple sequence values within a single operation. + + o When a sequence value associated with a state-owner is unavailable + for checking because the state-owner is unknown to the server, it + takes no part in the comparison. + + o When any of the state-owner sequence values are invalid, + NFS4ERR_BAD_SEQID is returned. When a stateid sequence is + checked, NFS4ERR_BAD_STATEID or NFS4ERR_OLD_STATEID is returned as + appropriate, but NFS4ERR_BAD_SEQID has priority. + + o When any one of the sequence values matches a previous request, + for a state-owner, it is treated as a retransmission and not + re-executed. When the type of the operation does not match that + originally used, NFS4ERR_BAD_SEQID is returned. When the server + can determine that the request differs from the original, it may + return NFS4ERR_BAD_SEQID. + + o When multiple sequence values match previous operations but the + operations are not the same, NFS4ERR_BAD_SEQID is returned. + + + + + + + +Haynes & Noveck Standards Track [Page 114] + +RFC 7530 NFSv4 March 2015 + + + o When there are no sequence values available for comparison and the + operation is an OPEN, the server indicates to the client that an + OPEN_CONFIRM is required, unless it can conclusively determine + that confirmation is not required (e.g., by knowing that no + open-owner state has ever been released for the current clientid). + +9.1.10. Releasing State-Owner State + + When a particular state-owner no longer holds open or file locking + state at the server, the server may choose to release the sequence + number state associated with the state-owner. The server may make + this choice based on lease expiration, the reclamation of server + memory, or other implementation-specific details. Note that when + this is done, a retransmitted request, normally identified by a + matching state-owner sequence, may not be correctly recognized, so + that the client will not receive the original response that it would + have if the state-owner state was not released. + + If the server were able to be sure that a given state-owner would + never again be used by a client, such an issue could not arise. Even + when the state-owner state is released and the client subsequently + uses that state-owner, retransmitted requests will be detected as + invalid and the request not executed, although the client may have a + recovery path that is more complicated than simply getting the + original response back transparently. + + In any event, the server is able to safely release state-owner state + (in the sense that retransmitted requests will not be erroneously + acted upon) when the state-owner is not currently being utilized by + the client (i.e., there are no open files associated with an + open-owner and no lock stateids associated with a lock-owner). The + server may choose to hold the state-owner state in order to simplify + the recovery path, in the case in which retransmissions of currently + active requests are received. However, the period for which it + chooses to hold this state is implementation specific. + + In the case that a LOCK, LOCKU, OPEN_DOWNGRADE, or CLOSE is + retransmitted after the server has previously released the + state-owner state, the server will find that the state-owner has no + files open and an error will be returned to the client. If the + state-owner does have a file open, the stateid will not match and + again an error is returned to the client. + + + + + + + + + +Haynes & Noveck Standards Track [Page 115] + +RFC 7530 NFSv4 March 2015 + + +9.1.11. Use of Open Confirmation + + In the case that an OPEN is retransmitted and the open-owner is being + used for the first time or the open-owner state has been previously + released by the server, the use of the OPEN_CONFIRM operation will + prevent incorrect behavior. When the server observes the use of the + open-owner for the first time, it will direct the client to perform + the OPEN_CONFIRM for the corresponding OPEN. This sequence + establishes the use of an open-owner and associated sequence number. + Since the OPEN_CONFIRM sequence connects a new open-owner on the + server with an existing open-owner on a client, the sequence number + may have any valid (i.e., non-zero) value. The OPEN_CONFIRM step + assures the server that the value received is the correct one. (See + Section 16.18 for further details.) + + There are a number of situations in which the requirement to confirm + an OPEN would pose difficulties for the client and server, in that + they would be prevented from acting in a timely fashion on + information received, because that information would be provisional, + subject to deletion upon non-confirmation. Fortunately, these are + situations in which the server can avoid the need for confirmation + when responding to open requests. The two constraints are: + + o The server must not bestow a delegation for any open that would + require confirmation. + + o The server MUST NOT require confirmation on a reclaim-type open + (i.e., one specifying claim type CLAIM_PREVIOUS or + CLAIM_DELEGATE_PREV). + + These constraints are related in that reclaim-type opens are the only + ones in which the server may be required to send a delegation. For + CLAIM_NULL, sending the delegation is optional, while for + CLAIM_DELEGATE_CUR, no delegation is sent. + + Delegations being sent with an open requiring confirmation are + troublesome because recovering from non-confirmation adds undue + complexity to the protocol, while requiring confirmation on reclaim- + type opens poses difficulties in that the inability to resolve the + status of the reclaim until lease expiration may make it difficult to + have timely determination of the set of locks being reclaimed (since + the grace period may expire). + + Requiring open confirmation on reclaim-type opens is avoidable + because of the nature of the environments in which such opens are + done. For CLAIM_PREVIOUS opens, this is immediately after server + reboot, so there should be no time for open-owners to be created, + found to be unused, and recycled. For CLAIM_DELEGATE_PREV opens, + + + +Haynes & Noveck Standards Track [Page 116] + +RFC 7530 NFSv4 March 2015 + + + we are dealing with either a client reboot situation or a network + partition resulting in deletion of lease state (and returning + NFS4ERR_EXPIRED). A server that supports delegations can be sure + that no open-owners for that client have been recycled since client + initialization or deletion of lease state and thus can be confident + that confirmation will not be required. + +9.2. Lock Ranges + + The protocol allows a lock-owner to request a lock with a byte range + and then either upgrade or unlock a sub-range of the initial lock. + It is expected that this will be an uncommon type of request. In any + case, servers or server file systems may not be able to support + sub-range lock semantics. In the event that a server receives a + locking request that represents a sub-range of current locking state + for the lock-owner, the server is allowed to return the error + NFS4ERR_LOCK_RANGE to signify that it does not support sub-range lock + operations. Therefore, the client should be prepared to receive this + error and, if appropriate, report the error to the requesting + application. + + The client is discouraged from combining multiple independent locking + ranges that happen to be adjacent into a single request, since the + server may not support sub-range requests, and for reasons related to + the recovery of file locking state in the event of server failure. + As discussed in Section 9.6.2 below, the server may employ certain + optimizations during recovery that work effectively only when the + client's behavior during lock recovery is similar to the client's + locking behavior prior to server failure. + +9.3. Upgrading and Downgrading Locks + + If a client has a write lock on a record, it can request an atomic + downgrade of the lock to a read lock via the LOCK request, by setting + the type to READ_LT. If the server supports atomic downgrade, the + request will succeed. If not, it will return NFS4ERR_LOCK_NOTSUPP. + The client should be prepared to receive this error and, if + appropriate, report the error to the requesting application. + + If a client has a read lock on a record, it can request an atomic + upgrade of the lock to a write lock via the LOCK request by setting + the type to WRITE_LT or WRITEW_LT. If the server does not support + atomic upgrade, it will return NFS4ERR_LOCK_NOTSUPP. If the upgrade + can be achieved without an existing conflict, the request will + succeed. Otherwise, the server will return either NFS4ERR_DENIED or + NFS4ERR_DEADLOCK. The error NFS4ERR_DEADLOCK is returned if the + client issued the LOCK request with the type set to WRITEW_LT and the + + + + +Haynes & Noveck Standards Track [Page 117] + +RFC 7530 NFSv4 March 2015 + + + server has detected a deadlock. The client should be prepared to + receive such errors and, if appropriate, report them to the + requesting application. + +9.4. Blocking Locks + + Some clients require the support of blocking locks. The NFSv4 + protocol must not rely on a callback mechanism and therefore is + unable to notify a client when a previously denied lock has been + granted. Clients have no choice but to continually poll for the + lock. This presents a fairness problem. Two new lock types are + added, READW and WRITEW, and are used to indicate to the server that + the client is requesting a blocking lock. The server should maintain + an ordered list of pending blocking locks. When the conflicting lock + is released, the server may wait the lease period for the first + waiting client to re-request the lock. After the lease period + expires, the next waiting client request is allowed the lock. + Clients are required to poll at an interval sufficiently small that + it is likely to acquire the lock in a timely manner. The server is + not required to maintain a list of pending blocked locks, as it is + not used to provide correct operation but only to increase fairness. + Because of the unordered nature of crash recovery, storing of lock + state to stable storage would be required to guarantee ordered + granting of blocking locks. + + Servers may also note the lock types and delay returning denial of + the request to allow extra time for a conflicting lock to be + released, allowing a successful return. In this way, clients can + avoid the burden of needlessly frequent polling for blocking locks. + The server should take care with the length of delay in the event + that the client retransmits the request. + + If a server receives a blocking lock request, denies it, and then + later receives a non-blocking request for the same lock, which is + also denied, then it should remove the lock in question from its list + of pending blocking locks. Clients should use such a non-blocking + request to indicate to the server that this is the last time they + intend to poll for the lock, as may happen when the process + requesting the lock is interrupted. This is a courtesy to the + server, to prevent it from unnecessarily waiting a lease period + before granting other lock requests. However, clients are not + required to perform this courtesy, and servers must not depend on + them doing so. Also, clients must be prepared for the possibility + that this final locking request will be accepted. + + + + + + + +Haynes & Noveck Standards Track [Page 118] + +RFC 7530 NFSv4 March 2015 + + +9.5. Lease Renewal + + The purpose of a lease is to allow a server to remove stale locks + that are held by a client that has crashed or is otherwise + unreachable. It is not a mechanism for cache consistency, and lease + renewals may not be denied if the lease interval has not expired. + + The client can implicitly provide a positive indication that it is + still active and that the associated state held at the server, for + the client, is still valid. Any operation made with a valid clientid + (DELEGPURGE, LOCK, LOCKT, OPEN, RELEASE_LOCKOWNER, or RENEW) or a + valid stateid (CLOSE, DELEGRETURN, LOCK, LOCKU, OPEN, OPEN_CONFIRM, + OPEN_DOWNGRADE, READ, SETATTR, or WRITE) informs the server to renew + all of the leases for that client (i.e., all those sharing a given + client ID). In the latter case, the stateid must not be one of the + special stateids (anonymous stateid or READ bypass stateid). + + Note that if the client had restarted or rebooted, the client would + not be making these requests without issuing the SETCLIENTID/ + SETCLIENTID_CONFIRM sequence. The use of the SETCLIENTID/ + SETCLIENTID_CONFIRM sequence (one that changes the client verifier) + notifies the server to drop the locking state associated with the + client. SETCLIENTID/SETCLIENTID_CONFIRM never renews a lease. + + If the server has rebooted, the stateids (NFS4ERR_STALE_STATEID + error) or the client ID (NFS4ERR_STALE_CLIENTID error) will not be + valid, hence preventing spurious renewals. + + This approach allows for low-overhead lease renewal, which scales + well. In the typical case, no extra RPCs are required for lease + renewal, and in the worst case, one RPC is required every lease + period (i.e., a RENEW operation). The number of locks held by the + client is not a factor since all state for the client is involved + with the lease renewal action. + + Since all operations that create a new lease also renew existing + leases, the server must maintain a common lease expiration time for + all valid leases for a given client. This lease time can then be + easily updated upon implicit lease renewal actions. + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 119] + +RFC 7530 NFSv4 March 2015 + + +9.6. Crash Recovery + + The important requirement in crash recovery is that both the client + and the server know when the other has failed. Additionally, it is + required that a client sees a consistent view of data across server + restarts or reboots. All READ and WRITE operations that may have + been queued within the client or network buffers must wait until the + client has successfully recovered the locks protecting the READ and + WRITE operations. + +9.6.1. Client Failure and Recovery + + In the event that a client fails, the server may recover the client's + locks when the associated leases have expired. Conflicting locks + from another client may only be granted after this lease expiration. + If the client is able to restart or reinitialize within the lease + period, the client may be forced to wait the remainder of the lease + period before obtaining new locks. + + To minimize client delay upon restart, open and lock requests are + associated with an instance of the client by a client-supplied + verifier. This verifier is part of the initial SETCLIENTID call made + by the client. The server returns a client ID as a result of the + SETCLIENTID operation. The client then confirms the use of the + client ID with SETCLIENTID_CONFIRM. The client ID in combination + with an opaque owner field is then used by the client to identify the + open-owner for OPEN. This chain of associations is then used to + identify all locks for a particular client. + + Since the verifier will be changed by the client upon each + initialization, the server can compare a new verifier to the verifier + associated with currently held locks and determine that they do not + match. This signifies the client's new instantiation and subsequent + loss of locking state. As a result, the server is free to release + all locks held that are associated with the old client ID that was + derived from the old verifier. + + Note that the verifier must have the same uniqueness properties of + the verifier for the COMMIT operation. + +9.6.2. Server Failure and Recovery + + If the server loses locking state (usually as a result of a restart + or reboot), it must allow clients time to discover this fact and + re-establish the lost locking state. The client must be able to + re-establish the locking state without having the server deny valid + requests because the server has granted conflicting access to another + client. Likewise, if there is the possibility that clients have + + + +Haynes & Noveck Standards Track [Page 120] + +RFC 7530 NFSv4 March 2015 + + + not yet re-established their locking state for a file, the server + must disallow READ and WRITE operations for that file. The duration + of this recovery period is equal to the duration of the lease period. + + A client can determine that server failure (and thus loss of locking + state) has occurred, when it receives one of two errors. The + NFS4ERR_STALE_STATEID error indicates a stateid invalidated by a + reboot or restart. The NFS4ERR_STALE_CLIENTID error indicates a + client ID invalidated by reboot or restart. When either of these is + received, the client must establish a new client ID (see + Section 9.1.1) and re-establish the locking state as discussed below. + + The period of special handling of locking and READs and WRITEs, equal + in duration to the lease period, is referred to as the "grace + period". During the grace period, clients recover locks and the + associated state by reclaim-type locking requests (i.e., LOCK + requests with reclaim set to TRUE and OPEN operations with a claim + type of either CLAIM_PREVIOUS or CLAIM_DELEGATE_PREV). During the + grace period, the server must reject READ and WRITE operations and + non-reclaim locking requests (i.e., other LOCK and OPEN operations) + with an error of NFS4ERR_GRACE. + + If the server can reliably determine that granting a non-reclaim + request will not conflict with reclamation of locks by other clients, + the NFS4ERR_GRACE error does not have to be returned and the + non-reclaim client request can be serviced. For the server to be + able to service READ and WRITE operations during the grace period, it + must again be able to guarantee that no possible conflict could arise + between an impending reclaim locking request and the READ or WRITE + operation. If the server is unable to offer that guarantee, the + NFS4ERR_GRACE error must be returned to the client. + + For a server to provide simple, valid handling during the grace + period, the easiest method is to simply reject all non-reclaim + locking requests and READ and WRITE operations by returning the + NFS4ERR_GRACE error. However, a server may keep information about + granted locks in stable storage. With this information, the server + could determine if a regular lock or READ or WRITE operation can be + safely processed. + + For example, if a count of locks on a given file is available in + stable storage, the server can track reclaimed locks for the file, + and when all reclaims have been processed, non-reclaim locking + requests may be processed. This way, the server can ensure that + non-reclaim locking requests will not conflict with potential reclaim + requests. With respect to I/O requests, if the server is able to + + + + + +Haynes & Noveck Standards Track [Page 121] + +RFC 7530 NFSv4 March 2015 + + + determine that there are no outstanding reclaim requests for a file + by information from stable storage or another similar mechanism, the + processing of I/O requests could proceed normally for the file. + + To reiterate, for a server that allows non-reclaim lock and I/O + requests to be processed during the grace period, it MUST determine + that no lock subsequently reclaimed will be rejected and that no lock + subsequently reclaimed would have prevented any I/O operation + processed during the grace period. + + Clients should be prepared for the return of NFS4ERR_GRACE errors for + non-reclaim lock and I/O requests. In this case, the client should + employ a retry mechanism for the request. A delay (on the order of + several seconds) between retries should be used to avoid overwhelming + the server. Further discussion of the general issue is included in + [Floyd]. The client must account for the server that is able to + perform I/O and non-reclaim locking requests within the grace period + as well as those that cannot do so. + + A reclaim-type locking request outside the server's grace period can + only succeed if the server can guarantee that no conflicting lock or + I/O request has been granted since reboot or restart. + + A server may, upon restart, establish a new value for the lease + period. Therefore, clients should, once a new client ID is + established, refetch the lease_time attribute and use it as the basis + for lease renewal for the lease associated with that server. + However, the server must establish, for this restart event, a grace + period at least as long as the lease period for the previous server + instantiation. This allows the client state obtained during the + previous server instance to be reliably re-established. + +9.6.3. Network Partitions and Recovery + + If the duration of a network partition is greater than the lease + period provided by the server, the server will have not received a + lease renewal from the client. If this occurs, the server may cancel + the lease and free all locks held for the client. As a result, all + stateids held by the client will become invalid or stale. Once the + client is able to reach the server after such a network partition, + all I/O submitted by the client with the now invalid stateids will + fail with the server returning the error NFS4ERR_EXPIRED. Once this + error is received, the client will suitably notify the application + that held the lock. + + + + + + + +Haynes & Noveck Standards Track [Page 122] + +RFC 7530 NFSv4 March 2015 + + +9.6.3.1. Courtesy Locks + + As a courtesy to the client or as an optimization, the server may + continue to hold locks, including delegations, on behalf of a client + for which recent communication has extended beyond the lease period, + delaying the cancellation of the lease. If the server receives a + lock or I/O request that conflicts with one of these courtesy locks + or if it runs out of resources, the server MAY cause lease + cancellation to occur at that time and henceforth return + NFS4ERR_EXPIRED when any of the stateids associated with the freed + locks is used. If lease cancellation has not occurred and the server + receives a lock or I/O request that conflicts with one of the + courtesy locks, the requirements are as follows: + + o In the case of a courtesy lock that is not a delegation, it MUST + free the courtesy lock and grant the new request. + + o In the case of a lock or an I/O request that conflicts with a + delegation that is being held as a courtesy lock, the server MAY + delay resolution of the request but MUST NOT reject the request + and MUST free the delegation and grant the new request eventually. + + o In the case of a request for a delegation that conflicts with a + delegation that is being held as a courtesy lock, the server MAY + grant the new request or not as it chooses, but if it grants the + conflicting request, the delegation held as a courtesy lock MUST + be freed. + + If the server does not reboot or cancel the lease before the network + partition is healed, when the original client tries to access a + courtesy lock that was freed, the server SHOULD send back an + NFS4ERR_BAD_STATEID to the client. If the client tries to access a + courtesy lock that was not freed, then the server SHOULD mark all of + the courtesy locks as implicitly being renewed. + +9.6.3.2. Lease Cancellation + + As a result of lease expiration, leases may be canceled, either + immediately upon expiration or subsequently, depending on the + occurrence of a conflicting lock or extension of the period of + partition beyond what the server will tolerate. + + When a lease is canceled, all locking state associated with it is + freed, and the use of any of the associated stateids will result in + NFS4ERR_EXPIRED being returned. Similarly, the use of the associated + clientid will result in NFS4ERR_EXPIRED being returned. + + + + + +Haynes & Noveck Standards Track [Page 123] + +RFC 7530 NFSv4 March 2015 + + + The client should recover from this situation by using SETCLIENTID + followed by SETCLIENTID_CONFIRM, in order to establish a new + clientid. Once a lock is obtained using this clientid, a lease will + be established. + +9.6.3.3. Client's Reaction to a Freed Lock + + There is no way for a client to predetermine how a given server is + going to behave during a network partition. When the partition + heals, the client still has either all of its locks, some of its + locks, or none of them. The client will be able to examine the + various error return values to determine its response. + + NFS4ERR_EXPIRED: + + All locks have been freed as a result of a lease cancellation that + occurred during the partition. The client should use a + SETCLIENTID to recover. + + NFS4ERR_ADMIN_REVOKED: + + The current lock has been revoked before, during, or after the + partition. The client SHOULD handle this error as it normally + would. + + NFS4ERR_BAD_STATEID: + + The current lock has been revoked/released during the partition, + and the server did not reboot. Other locks MAY still be renewed. + The client need not do a SETCLIENTID and instead SHOULD probe via + a RENEW call. + + NFS4ERR_RECLAIM_BAD: + + The current lock has been revoked during the partition, and the + server rebooted. The server might have no information on the + other locks. They may still be renewable. + + NFS4ERR_NO_GRACE: + + The client's locks have been revoked during the partition, and the + server rebooted. None of the client's locks will be renewable. + + NFS4ERR_OLD_STATEID: + + The server has not rebooted. The client SHOULD handle this error + as it normally would. + + + + +Haynes & Noveck Standards Track [Page 124] + +RFC 7530 NFSv4 March 2015 + + +9.6.3.4. Edge Conditions + + When a network partition is combined with a server reboot, then both + the server and client have responsibilities to ensure that the client + does not reclaim a lock that it should no longer be able to access. + Briefly, those are: + + o Client's responsibility: A client MUST NOT attempt to reclaim any + locks that it did not hold at the end of its most recent + successfully established client lease. + + o Server's responsibility: A server MUST NOT allow a client to + reclaim a lock unless it knows that it could not have since + granted a conflicting lock. However, in deciding whether a + conflicting lock could have been granted, it is permitted to + assume that its clients are responsible, as above. + + A server may consider a client's lease "successfully established" + once it has received an OPEN operation from that client. + + The above are directed to CLAIM_PREVIOUS reclaims and not to + CLAIM_DELEGATE_PREV reclaims, which generally do not involve a server + reboot. However, when a server persistently stores delegation + information to support CLAIM_DELEGATE_PREV across a period in which + both client and server are down at the same time, similar strictures + apply. + + The next sections give examples showing what can go wrong if these + responsibilities are neglected and also provide examples of server + implementation strategies that could meet a server's + responsibilities. + +9.6.3.4.1. First Server Edge Condition + + The first edge condition has the following scenario: + + 1. Client A acquires a lock. + + 2. Client A and the server experience mutual network partition, such + that client A is unable to renew its lease. + + 3. Client A's lease expires, so the server releases the lock. + + 4. Client B acquires a lock that would have conflicted with that of + client A. + + 5. Client B releases the lock. + + + + +Haynes & Noveck Standards Track [Page 125] + +RFC 7530 NFSv4 March 2015 + + + 6. The server reboots. + + 7. The network partition between client A and the server heals. + + 8. Client A issues a RENEW operation and gets back an + NFS4ERR_STALE_CLIENTID. + + 9. Client A reclaims its lock within the server's grace period. + + Thus, at the final step, the server has erroneously granted + client A's lock reclaim. If client B modified the object the lock + was protecting, client A will experience object corruption. + +9.6.3.4.2. Second Server Edge Condition + + The second known edge condition follows: + + 1. Client A acquires a lock. + + 2. The server reboots. + + 3. Client A and the server experience mutual network partition, + such that client A is unable to reclaim its lock within the + grace period. + + 4. The server's reclaim grace period ends. Client A has no locks + recorded on the server. + + 5. Client B acquires a lock that would have conflicted with that of + client A. + + 6. Client B releases the lock. + + 7. The server reboots a second time. + + 8. The network partition between client A and the server heals. + + 9. Client A issues a RENEW operation and gets back an + NFS4ERR_STALE_CLIENTID. + + 10. Client A reclaims its lock within the server's grace period. + + As with the first edge condition, the final step of the scenario of + the second edge condition has the server erroneously granting + client A's lock reclaim. + + + + + + +Haynes & Noveck Standards Track [Page 126] + +RFC 7530 NFSv4 March 2015 + + +9.6.3.4.3. Handling Server Edge Conditions + + In both of the above examples, the client attempts reclaim of a lock + that it held at the end of its most recent successfully established + lease; thus, it has fulfilled its responsibility. + + The server, however, has failed, by granting a reclaim, despite + having granted a conflicting lock since the reclaimed lock was last + held. + + Solving these edge conditions requires that the server either (1) + assume after it reboots that an edge condition occurs, and thus + return NFS4ERR_NO_GRACE for all reclaim attempts, or (2) record some + information in stable storage. The amount of information the server + records in stable storage is in inverse proportion to how harsh the + server wants to be whenever the edge conditions occur. The server + that is completely tolerant of all edge conditions will record in + stable storage every lock that is acquired, removing the lock record + from stable storage only when the lock is unlocked by the client and + the lock's owner advances the sequence number such that the lock + release is not the last stateful event for the owner's sequence. For + the two aforementioned edge conditions, the harshest a server can be, + and still support a grace period for reclaims, requires that the + server record in stable storage some minimal information. For + example, a server implementation could, for each client, save in + stable storage a record containing: + + o the client's id string. + + o a boolean that indicates if the client's lease expired or if there + was administrative intervention (see Section 9.8) to revoke a + byte-range lock, share reservation, or delegation. + + o a timestamp that is updated the first time after a server boot or + reboot the client acquires byte-range locking, share reservation, + or delegation state on the server. The timestamp need not be + updated on subsequent lock requests until the server reboots. + + The server implementation would also record in stable storage the + timestamps from the two most recent server reboots. + + Assuming the above record keeping, for the first edge condition, + after the server reboots, the record that client A's lease expired + means that another client could have acquired a conflicting record + lock, share reservation, or delegation. Hence, the server must + reject a reclaim from client A with the error NFS4ERR_NO_GRACE or + NFS4ERR_RECLAIM_BAD. + + + + +Haynes & Noveck Standards Track [Page 127] + +RFC 7530 NFSv4 March 2015 + + + For the second edge condition, after the server reboots for a second + time, the record that the client had an unexpired record lock, share + reservation, or delegation established before the server's previous + incarnation means that the server must reject a reclaim from client A + with the error NFS4ERR_NO_GRACE or NFS4ERR_RECLAIM_BAD. + + Regardless of the level and approach to record keeping, the server + MUST implement one of the following strategies (which apply to + reclaims of share reservations, byte-range locks, and delegations): + + 1. Reject all reclaims with NFS4ERR_NO_GRACE. This is extremely + harsh but is necessary if the server does not want to record lock + state in stable storage. + + 2. Record sufficient state in stable storage to meet its + responsibilities. In doubt, the server should err on the side of + being harsh. + + In the event that, after a server reboot, the server determines + that there is unrecoverable damage or corruption to stable + storage, then for all clients and/or locks affected, the server + MUST return NFS4ERR_NO_GRACE. + +9.6.3.4.4. Client Edge Condition + + A third edge condition affects the client and not the server. If the + server reboots in the middle of the client reclaiming some locks and + then a network partition is established, the client might be in the + situation of having reclaimed some, but not all, locks. In that + case, a conservative client would assume that the non-reclaimed locks + were revoked. + + The third known edge condition follows: + + 1. Client A acquires a lock 1. + + 2. Client A acquires a lock 2. + + 3. The server reboots. + + 4. Client A issues a RENEW operation and gets back an + NFS4ERR_STALE_CLIENTID. + + 5. Client A reclaims its lock 1 within the server's grace period. + + 6. Client A and the server experience mutual network partition, + such that client A is unable to reclaim its remaining locks + within the grace period. + + + +Haynes & Noveck Standards Track [Page 128] + +RFC 7530 NFSv4 March 2015 + + + 7. The server's reclaim grace period ends. + + 8. Client B acquires a lock that would have conflicted with + client A's lock 2. + + 9. Client B releases the lock. + + 10. The server reboots a second time. + + 11. The network partition between client A and the server heals. + + 12. Client A issues a RENEW operation and gets back an + NFS4ERR_STALE_CLIENTID. + + 13. Client A reclaims both lock 1 and lock 2 within the server's + grace period. + + At the last step, the client reclaims lock 2 as if it had held that + lock continuously, when in fact a conflicting lock was granted to + client B. + + This occurs because the client failed its responsibility, by + attempting to reclaim lock 2 even though it had not held that lock at + the end of the lease that was established by the SETCLIENTID after + the first server reboot. (The client did hold lock 2 on a previous + lease, but it is only the most recent lease that matters.) + + A server could avoid this situation by rejecting the reclaim of + lock 2. However, to do so accurately, it would have to ensure that + additional information about individual locks held survives a reboot. + Server implementations are not required to do that, so the client + must not assume that the server will. + + Instead, a client MUST reclaim only those locks that it successfully + acquired from the previous server instance, omitting any that it + failed to reclaim before a new reboot. Thus, in the last step above, + client A should reclaim only lock 1. + +9.6.3.4.5. Client's Handling of Reclaim Errors + + A mandate for the client's handling of the NFS4ERR_NO_GRACE and + NFS4ERR_RECLAIM_BAD errors is outside the scope of this + specification, since the strategies for such handling are very + dependent on the client's operating environment. However, one + potential approach is described below. + + + + + + +Haynes & Noveck Standards Track [Page 129] + +RFC 7530 NFSv4 March 2015 + + + When the client's reclaim fails, it could examine the change + attribute of the objects the client is trying to reclaim state for, + and use that to determine whether to re-establish the state via + normal OPEN or LOCK requests. This is acceptable, provided the + client's operating environment allows it. In other words, the client + implementer is advised to document the behavior for his users. The + client could also inform the application that its byte-range lock or + share reservations (whether they were delegated or not) have been + lost, such as via a UNIX signal, a GUI pop-up window, etc. See + Section 10.5 for a discussion of what the client should do for + dealing with unreclaimed delegations on client state. + + For further discussion of revocation of locks, see Section 9.8. + +9.7. Recovery from a Lock Request Timeout or Abort + + 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 + 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 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 client resynchronize state with the server before it attempts any + other operation that takes a seqid and/or a stateid with the same + state-owner. This is straightforward to do without a special + resynchronize operation. + + Since the server maintains the last lock request and response + received on the state-owner, for each state-owner, the client should + 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 + lock operation for the state-owner, it can send the cached request, + if 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 + result or, if it never saw the request, perform it. The client can + follow up with a request to remove the state (e.g., a LOCKU or CLOSE + operation). With this approach, the sequencing and stateid + information on the client and server for the given state-owner will + resynchronize, and in turn the lock state will resynchronize. + +9.8. Server Revocation of Locks + + 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 + its locks have been or may have been revoked, the client is + responsible for validating the state information between itself and + the server. Validating locking state for the client means that it + must verify or reclaim state for each lock currently held. + + + +Haynes & Noveck Standards Track [Page 130] + +RFC 7530 NFSv4 March 2015 + + + The first instance of lock revocation is upon server reboot or + re-initialization. In this instance, the client will receive an + error (NFS4ERR_STALE_STATEID or NFS4ERR_STALE_CLIENTID) and the + client will proceed with normal crash recovery as described in the + previous section. + + The second lock revocation event is the inability to renew the lease + before expiration. While this is considered a rare or unusual event, + the client must be prepared to recover. Both the server and client + will be able to detect the failure to renew the lease and are capable + of recovering without data corruption. For the server, it tracks the + last renewal event serviced for the client and knows when the lease + will expire. Similarly, the client must track operations that will + renew the lease period. Using the time that each such request was + sent and the time that the corresponding reply was received, the + client should bound the time that the corresponding renewal could + have occurred on the server and thus determine if it is possible that + a lease period expiration could have occurred. + + The third lock revocation event can occur as a result of + administrative intervention within the lease period. While this is + considered a rare event, it is possible that the server's + administrator has decided to release or revoke a particular lock held + by the client. As a result of revocation, the client will receive an + error of NFS4ERR_ADMIN_REVOKED. In this instance, the client may + assume that only the state-owner's locks have been lost. The client + notifies the lock holder appropriately. The client cannot assume + that the lease period has been renewed as a result of a failed + operation. + + When the client determines the lease period may have expired, the + client must mark all locks held for the associated lease as + "unvalidated". This means the client has been unable to re-establish + or confirm the appropriate lock state with the server. As described + in Section 9.6, there are scenarios in which the server may grant + conflicting locks after the lease period has expired for a client. + When it is possible that the lease period has expired, the client + must validate each lock currently held to ensure that a conflicting + lock has not been granted. The client may accomplish this task by + issuing an I/O request; if there is no relevant I/O pending, a + zero-length read specifying the stateid associated with the lock in + question can be synthesized to trigger the renewal. If the response + to the request is success, the client has validated all of the locks + governed by that stateid and re-established the appropriate state + between itself and the server. + + + + + + +Haynes & Noveck Standards Track [Page 131] + +RFC 7530 NFSv4 March 2015 + + + If the I/O request is not successful, then one or more of the locks + associated with the stateid were revoked by the server, and the + client must notify the owner. + +9.9. Share Reservations + + A share reservation is a mechanism to control access to a file. It + is a separate and independent mechanism from byte-range locking. + When a client opens a file, it issues an OPEN operation to the server + specifying the type of access required (READ, WRITE, or BOTH) and the + type of access to deny others (OPEN4_SHARE_DENY_NONE, + OPEN4_SHARE_DENY_READ, OPEN4_SHARE_DENY_WRITE, or + OPEN4_SHARE_DENY_BOTH). If the OPEN fails, the client will fail the + application's open request. + + Pseudo-code definition of the semantics: + + if (request.access == 0) + return (NFS4ERR_INVAL) + else if ((request.access & file_state.deny) || + (request.deny & file_state.access)) + return (NFS4ERR_DENIED) + + This checking of share reservations on OPEN is done with no exception + for an existing OPEN for the same open-owner. + + The constants used for the OPEN and OPEN_DOWNGRADE operations for the + access and deny fields are as follows: + + const OPEN4_SHARE_ACCESS_READ = 0x00000001; + const OPEN4_SHARE_ACCESS_WRITE = 0x00000002; + const OPEN4_SHARE_ACCESS_BOTH = 0x00000003; + + const OPEN4_SHARE_DENY_NONE = 0x00000000; + const OPEN4_SHARE_DENY_READ = 0x00000001; + const OPEN4_SHARE_DENY_WRITE = 0x00000002; + const OPEN4_SHARE_DENY_BOTH = 0x00000003; + +9.10. OPEN/CLOSE Operations + + To provide correct share semantics, a client MUST use the OPEN + operation to obtain the initial filehandle and indicate the desired + access and what access, if any, to deny. Even if the client intends + to use one of the special stateids (anonymous stateid or READ bypass + stateid), it must still obtain the filehandle for the regular file + with the OPEN operation so the appropriate share semantics can be + + + + + +Haynes & Noveck Standards Track [Page 132] + +RFC 7530 NFSv4 March 2015 + + + applied. Clients that do not have a deny mode built into their + programming interfaces for opening a file should request a deny mode + of OPEN4_SHARE_DENY_NONE. + + The OPEN operation with the CREATE flag also subsumes the CREATE + operation for regular files as used in previous versions of the NFS + protocol. This allows a create with a share to be done atomically. + + The CLOSE operation removes all share reservations held by the + open-owner on that file. If byte-range locks are held, the client + SHOULD release all locks before issuing a CLOSE. The server MAY free + all outstanding locks on CLOSE, but some servers may not support the + CLOSE of a file that still has byte-range locks held. The server + MUST return failure, NFS4ERR_LOCKS_HELD, if any locks would exist + after the CLOSE. + + The LOOKUP operation will return a filehandle without establishing + any lock state on the server. Without a valid stateid, the server + will assume that the client has the least access. For example, if + one client opened a file with OPEN4_SHARE_DENY_BOTH and another + client accesses the file via a filehandle obtained through LOOKUP, + the second client could only read the file using the special READ + bypass 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 stateid would not be allowed access. + +9.10.1. Close and Retention of State Information + + Since a CLOSE operation requests deallocation of a stateid, dealing + with retransmission of the CLOSE may pose special difficulties, since + the state information, which normally would be used to determine the + state of the open file being designated, might be deallocated, + resulting in an NFS4ERR_BAD_STATEID error. + + Servers may deal with this problem in a number of ways. To provide + the greatest degree of assurance that the protocol is being used + properly, a server should, rather than deallocate the stateid, mark + it as close-pending, and retain the stateid with this status, until + later deallocation. In this way, a retransmitted CLOSE can be + recognized since the stateid points to state information with this + distinctive status, so that it can be handled without error. + + + + + + + + + + +Haynes & Noveck Standards Track [Page 133] + +RFC 7530 NFSv4 March 2015 + + + When adopting this strategy, a server should retain the state + information until the earliest of: + + o Another validly sequenced request for the same open-owner, that is + not a retransmission. + + o The time that an open-owner is freed by the server due to period + with no activity. + + o All locks for the client are freed as a result of a SETCLIENTID. + + Servers may avoid this complexity, at the cost of less complete + protocol error checking, by simply responding NFS4_OK in the event of + a CLOSE for a deallocated stateid, on the assumption that this case + must be caused by a retransmitted close. When adopting this + approach, it is desirable to at least log an error when returning a + no-error indication in this situation. If the server maintains a + reply-cache mechanism, it can verify that the CLOSE is indeed a + retransmission and avoid error logging in most cases. + +9.11. Open Upgrade and Downgrade + + When an OPEN is done for a file and the open-owner for which the open + is being done already has the file open, the result is to upgrade the + open file status maintained on the server to include the access and + deny bits specified by the new OPEN as well as those for the existing + OPEN. The result is that there is one open file, as far as the + protocol is concerned, and it includes the union of the access and + deny bits for all of the OPEN requests completed. Only a single + CLOSE will be done to reset the effects of both OPENs. Note that the + client, when issuing the OPEN, may not know that the same file is in + fact being opened. The above only applies if both OPENs result in + the OPENed object being designated by the same filehandle. + + When the server chooses to export multiple filehandles corresponding + to the same file object and returns different filehandles on two + different OPENs of the same file object, the server MUST NOT "OR" + together the access and deny bits and coalesce the two open files. + Instead, the server must maintain separate OPENs with separate + stateids and will require separate CLOSEs to free them. + + When multiple open files on the client are merged into a single open + file object on the server, the close of one of the open files (on the + client) may necessitate change of the access and deny status of the + open file on the server. This is because the union of the access and + deny bits for the remaining opens may be smaller (i.e., a proper + subset) than previously. The OPEN_DOWNGRADE operation is used to + make the necessary change, and the client should use it to update the + + + +Haynes & Noveck Standards Track [Page 134] + +RFC 7530 NFSv4 March 2015 + + + server so that share reservation requests by other clients are + handled properly. The stateid returned has the same "other" field as + that passed to the server. The seqid value in the returned stateid + MUST be incremented (Section 9.1.4), even in situations in which + there has been no change to the access and deny bits for the file. + +9.12. Short and Long Leases + + When determining the time period for the server lease, the usual + lease trade-offs apply. Short leases are good for fast server + recovery at a cost of increased RENEW or READ (with zero length) + requests. Longer leases are certainly kinder and gentler to servers + trying to handle very large numbers of clients. The number of RENEW + requests drops in proportion to the lease time. The disadvantages of + long leases are slower recovery after server failure (the server must + wait for the leases to expire and the grace period to elapse before + granting new lock requests) and increased file contention (if the + client fails to transmit an unlock request, then the server must wait + for lease expiration before granting new locks). + + Long leases are usable if the server is able to store lease state in + non-volatile memory. Upon recovery, the server can reconstruct the + lease state from its non-volatile memory and continue operation with + its clients, and therefore long leases would not be an issue. + +9.13. Clocks, Propagation Delay, and Calculating Lease Expiration + + To avoid the need for synchronized clocks, lease times are granted by + the server as a time delta. However, there is a requirement that the + client and server clocks do not drift excessively over the duration + of the lock. There is also the issue of propagation delay across the + network -- which could easily be several hundred milliseconds -- as + well as the possibility that requests will be lost and need to be + retransmitted. + + To take propagation delay into account, the client should subtract it + from lease times (e.g., if the client estimates the one-way + propagation delay as 200 msec, then it can assume that the lease is + already 200 msec old when it gets it). In addition, it will take + another 200 msec to get a response back to the server. So the client + must send a lock renewal or write data back to the server 400 msec + before the lease would expire. + + The server's lease period configuration should take into account the + network distance of the clients that will be accessing the server's + resources. It is expected that the lease period will take into + account the network propagation delays and other network delay + + + + +Haynes & Noveck Standards Track [Page 135] + +RFC 7530 NFSv4 March 2015 + + + factors for the client population. Since the protocol does not allow + for an automatic method to determine an appropriate lease period, the + server's administrator may have to tune the lease period. + +9.14. Migration, Replication, and State + + When responsibility for handling a given file system is transferred + to a new server (migration) or the client chooses to use an + alternative server (e.g., in response to server unresponsiveness) in + the context of file system replication, the appropriate handling of + state shared between the client and server (i.e., locks, leases, + stateids, and client IDs) is as described below. The handling + differs between migration and replication. For a related discussion + of file server state and recovery of same, see the subsections of + Section 9.6. + + In cases in which one server is expected to accept opaque values from + the client that originated from another server, the servers SHOULD + encode the opaque values in big-endian byte order. If this is done, + the new server will be able to parse values like stateids, directory + cookies, filehandles, etc. even if their native byte order is + different from that of other servers cooperating in the replication + and migration of the file system. + +9.14.1. Migration and State + + In the case of migration, the servers involved in the migration of a + file system SHOULD transfer all server state from the original server + to the new server. This must be done in a way that is transparent to + the client. This state transfer will ease the client's transition + when a file system migration occurs. If the servers are successful + in transferring all state, the client will continue to use stateids + assigned by the original server. Therefore, the new server must + recognize these stateids as valid. This holds true for the client ID + as well. Since responsibility for an entire file system is + transferred with a migration event, there is no possibility that + conflicts will arise on the new server as a result of the transfer of + locks. + + As part of the transfer of information between servers, leases would + be transferred as well. The leases being transferred to the new + server will typically have a different expiration time from those for + the same client, previously on the old server. To maintain the + property that all leases on a given server for a given client expire + at the same time, the server should advance the expiration time to + the later of the leases being transferred or the leases already + present. This allows the client to maintain lease renewal of both + classes without special effort. + + + +Haynes & Noveck Standards Track [Page 136] + +RFC 7530 NFSv4 March 2015 + + + The servers may choose not to transfer the state information upon + migration. However, this choice is discouraged. In this case, when + the client presents state information from the original server (e.g., + in a RENEW operation or a READ operation of zero length), the client + must be prepared to receive either NFS4ERR_STALE_CLIENTID or + NFS4ERR_STALE_STATEID from the new server. The client should then + recover its state information as it normally would in response to a + server failure. The new server must take care to allow for the + recovery of state information as it would in the event of server + restart. + + A client SHOULD re-establish new callback information with the new + server as soon as possible, according to sequences described in + Sections 16.33 and 16.34. This ensures that server operations are + not blocked by the inability to recall delegations. + +9.14.2. Replication and State + + Since client switch-over in the case of replication is not under + server control, the handling of state is different. In this case, + leases, stateids, and client IDs do not have validity across a + transition from one server to another. The client must re-establish + its locks on the new server. This can be compared to the + re-establishment of locks by means of reclaim-type requests after a + server reboot. The difference is that the server has no provision to + distinguish requests reclaiming locks from those obtaining new locks + or to defer the latter. Thus, a client re-establishing a lock on the + new server (by means of a LOCK or OPEN request), may have the + requests denied due to a conflicting lock. Since replication is + intended for read-only use of file systems, such denial of locks + should not pose large difficulties in practice. When an attempt to + re-establish a lock on a new server is denied, the client should + treat the situation as if its original lock had been revoked. + +9.14.3. Notification of Migrated Lease + + In the case of lease renewal, the client may not be submitting + requests for a file system that has been migrated to another server. + This can occur because of the implicit lease renewal mechanism. The + client renews leases for all file systems when submitting a request + to any one file system at the server. + + In order for the client to schedule renewal of leases that may have + been relocated to the new server, the client must find out about + lease relocation before those leases expire. To accomplish this, all + operations that implicitly renew leases for a client (such as OPEN, + CLOSE, READ, WRITE, RENEW, LOCK, and others) will return the error + NFS4ERR_LEASE_MOVED if responsibility for any of the leases to be + + + +Haynes & Noveck Standards Track [Page 137] + +RFC 7530 NFSv4 March 2015 + + + renewed has been transferred to a new server. This condition will + continue until the client receives an NFS4ERR_MOVED error and the + server receives the subsequent GETATTR(fs_locations) for an access to + each file system for which a lease has been moved to a new server. + By convention, the compound including the GETATTR(fs_locations) + SHOULD append a RENEW operation to permit the server to identify the + client doing the access. + + Upon receiving the NFS4ERR_LEASE_MOVED error, a client that supports + file system migration MUST probe all file systems from that server on + which it holds open state. Once the client has successfully probed + all those file systems that are migrated, the server MUST resume + normal handling of stateful requests from that client. + + In order to support legacy clients that do not handle the + NFS4ERR_LEASE_MOVED error correctly, the server SHOULD time out after + a wait of at least two lease periods, at which time it will resume + normal handling of stateful requests from all clients. If a client + attempts to access the migrated files, the server MUST reply with + NFS4ERR_MOVED. + + When the client receives an NFS4ERR_MOVED error, the client can + follow the normal process to obtain the new server information + (through the fs_locations attribute) and perform renewal of those + leases on the new server. If the server has not had state + transferred to it transparently, the client will receive either + NFS4ERR_STALE_CLIENTID or NFS4ERR_STALE_STATEID from the new server, + as described above. The client can then recover state information as + it does in the event of server failure. + +9.14.4. Migration and the lease_time Attribute + + In order that the client may appropriately manage its leases in the + case of migration, the destination server must establish proper + values for the lease_time attribute. + + When state is transferred transparently, that state should include + the correct value of the lease_time attribute. The lease_time + attribute on the destination server must never be less than that on + the source since this would result in premature expiration of leases + granted by the source server. Upon migration, in which state is + transferred transparently, the client is under no obligation to + refetch the lease_time attribute and may continue to use the value + previously fetched (on the source server). + + If state has not been transferred transparently (i.e., the client + sees a real or simulated server reboot), the client should fetch the + value of lease_time on the new (i.e., destination) server and use it + + + +Haynes & Noveck Standards Track [Page 138] + +RFC 7530 NFSv4 March 2015 + + + for subsequent locking requests. However, the server must respect a + grace period at least as long as the lease_time on the source server, + in order to ensure that clients have ample time to reclaim their + locks before potentially conflicting non-reclaimed locks are granted. + The means by which the new server obtains the value of lease_time on + the old server is left to the server implementations. It is not + specified by the NFSv4 protocol. + +10. Client-Side Caching + + Client-side caching of data, file attributes, and filenames is + essential to providing good performance with the NFS protocol. + Providing distributed cache coherence is a difficult problem, and + previous versions of the NFS protocol have not attempted it. + Instead, several NFS client implementation techniques have been used + to reduce the problems that a lack of coherence poses for users. + These techniques have not been clearly defined by earlier protocol + specifications, and it is often unclear what is valid or invalid + client behavior. + + The NFSv4 protocol uses many techniques similar to those that have + been used in previous protocol versions. The NFSv4 protocol does not + provide distributed cache coherence. However, it defines a more + limited set of caching guarantees to allow locks and share + reservations to be used without destructive interference from + client-side caching. + + In addition, the NFSv4 protocol introduces a delegation mechanism + that allows many decisions normally made by the server to be made + locally by clients. This mechanism provides efficient support of the + common cases where sharing is infrequent or where sharing is + read-only. + +10.1. Performance Challenges for Client-Side Caching + + Caching techniques used in previous versions of the NFS protocol have + been successful in providing good performance. However, several + scalability challenges can arise when those techniques are used with + very large numbers of clients. This is particularly true when + clients are geographically distributed, which classically increases + the latency for cache revalidation requests. + + The previous versions of the NFS protocol repeat their file data + cache validation requests at the time the file is opened. This + behavior can have serious performance drawbacks. A common case is + one in which a file is only accessed by a single client. Therefore, + sharing is infrequent. + + + + +Haynes & Noveck Standards Track [Page 139] + +RFC 7530 NFSv4 March 2015 + + + In this case, repeated reference to the server to find that no + conflicts exist is expensive. A better option with regards to + performance is to allow a client that repeatedly opens a file to do + so without reference to the server. This is done until potentially + conflicting operations from another client actually occur. + + A similar situation arises in connection with file locking. Sending + file lock and unlock requests to the server as well as the READ and + WRITE requests necessary to make data caching consistent with the + locking semantics (see Section 10.3.2) can severely limit + performance. When locking is used to provide protection against + infrequent conflicts, a large penalty is incurred. This penalty may + discourage the use of file locking by applications. + + The NFSv4 protocol provides more aggressive caching strategies with + the following design goals: + + o Compatibility with a large range of server semantics. + + o Providing the same caching benefits as previous versions of the + NFS protocol when unable to provide the more aggressive model. + + o Organizing requirements for aggressive caching so that a large + portion of the benefit can be obtained even when not all of the + requirements can be met. + + The appropriate requirements for the server are discussed in later + sections, in which specific forms of caching are covered (see + Section 10.4). + +10.2. Delegation and Callbacks + + Recallable delegation of server responsibilities for a file to a + client improves performance by avoiding repeated requests to the + server in the absence of inter-client conflict. With the use of a + "callback" RPC from server to client, a server recalls delegated + responsibilities when another client engages in the sharing of a + delegated file. + + A delegation is passed from the server to the client, specifying the + object of the delegation and the type of delegation. There are + different types of delegations, but each type contains a stateid to + be used to represent the delegation when performing operations that + depend on the delegation. This stateid is similar to those + associated with locks and share reservations but differs in that the + stateid for a delegation is associated with a client ID and may be + + + + + +Haynes & Noveck Standards Track [Page 140] + +RFC 7530 NFSv4 March 2015 + + + 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 + process or thread of control within it. + + Because callback RPCs may not work in all environments (due to + firewalls, for example), correct protocol operation does not depend + on them. Preliminary testing of callback functionality by means of a + CB_NULL procedure determines whether callbacks can be supported. The + CB_NULL procedure checks the continuity of the callback path. A + server makes a preliminary assessment of callback availability to a + given client and avoids delegating responsibilities until it has + determined that callbacks are supported. Because the granting of a + delegation is always conditional upon the absence of conflicting + access, clients must not assume that a delegation will be granted, + and they must always be prepared for OPENs to be processed without + any delegations being granted. + + Once granted, a delegation behaves in most ways like a lock. There + is an associated lease that is subject to renewal, together with all + of the other leases held by that client. + + Unlike locks, an operation by a second client to a delegated file + will cause the server to recall a delegation through a callback. + + On recall, the client holding the delegation must flush modified + state (such as modified data) to the server and return the + delegation. The conflicting request will not be acted on until the + recall is complete. The recall is considered complete when the + client returns the delegation or the server times out its wait for + the delegation to be returned and revokes the delegation as a result + of the timeout. In the interim, the server will either delay + responding to conflicting requests or respond to them with + NFS4ERR_DELAY. Following the resolution of the recall, the server + has the information necessary to grant or deny the second client's + request. + + At the time the client receives a delegation recall, it may have + substantial state that needs to be flushed to the server. Therefore, + the server should allow sufficient time for the delegation to be + returned since it may involve numerous RPCs to the server. If the + server is able to determine that the client is diligently flushing + state to the server as a result of the recall, the server MAY extend + the usual time allowed for a recall. However, the time allowed for + recall completion should not be unbounded. + + + + + + + +Haynes & Noveck Standards Track [Page 141] + +RFC 7530 NFSv4 March 2015 + + + An example of this is when responsibility to mediate opens on a given + file is delegated to a client (see Section 10.4). The server will + not know what opens are in effect on the client. Without this + knowledge, the server will be unable to determine if the access and + deny state for the file allows any particular open until the + delegation for the file has been returned. + + A client failure or a network partition can result in failure to + respond to a recall callback. In this case, the server will revoke + the delegation; this in turn will render useless any modified state + still on the client. + + Clients need to be aware that server implementers may enforce + practical limitations on the number of delegations issued. Further, + as there is no way to determine which delegations to revoke, the + server is allowed to revoke any. If the server is implemented to + revoke another delegation held by that client, then the client may + be able to determine that a limit has been reached because each new + delegation request results in a revoke. The client could then + determine which delegations it may not need and preemptively + release them. + +10.2.1. Delegation Recovery + + There are three situations that delegation recovery must deal with: + + o Client reboot or restart + + o Server reboot or restart (see Section 9.6.3.1) + + o Network partition (full or callback-only) + + In the event that the client reboots or restarts, the confirmation of + a SETCLIENTID done with an nfs_client_id4 with a new verifier4 value + will result in the release of byte-range locks and share + reservations. Delegations, however, may be treated a bit + differently. + + There will be situations in which delegations will need to be + re-established after a client reboots or restarts. The reason for + this is the client may have file data stored locally and this data + was associated with the previously held delegations. The client will + need to re-establish the appropriate file state on the server. + + To allow for this type of client recovery, the server MAY allow + delegations to be retained after other sorts of locks are released. + This implies that requests from other clients that conflict with + these delegations will need to wait. Because the normal recall + + + +Haynes & Noveck Standards Track [Page 142] + +RFC 7530 NFSv4 March 2015 + + + process may require significant time for the client to flush changed + state to the server, other clients need to be prepared for delays + that occur because of a conflicting delegation. In order to give + clients a chance to get through the reboot process -- during which + leases will not be renewed -- the server MAY extend the period for + delegation recovery beyond the typical lease expiration period. For + open delegations, such delegations that are not released are + reclaimed using OPEN with a claim type of CLAIM_DELEGATE_PREV. (See + Sections 10.5 and 16.16 for discussions of open delegation and the + details of OPEN, respectively.) + + A server MAY support a claim type of CLAIM_DELEGATE_PREV, but if it + does, it MUST NOT remove delegations upon SETCLIENTID_CONFIRM and + instead MUST make them available for client reclaim using + CLAIM_DELEGATE_PREV. The server MUST NOT remove the delegations + until either the client does a DELEGPURGE or one lease period has + elapsed from the time -- whichever is later -- of the + SETCLIENTID_CONFIRM or the last successful CLAIM_DELEGATE_PREV + reclaim. + + Note that the requirement stated above is not meant to imply that, + when the server is no longer obliged, as required above, to retain + delegation information, it should necessarily dispose of it. Some + specific cases are: + + o When the period is terminated by the occurrence of DELEGPURGE, + deletion of unreclaimed delegations is appropriate and desirable. + + o When the period is terminated by a lease period elapsing without a + successful CLAIM_DELEGATE_PREV reclaim, and that situation appears + to be the result of a network partition (i.e., lease expiration + has occurred), a server's lease expiration approach, possibly + including the use of courtesy locks, would normally provide for + the retention of unreclaimed delegations. Even in the event that + lease cancellation occurs, such delegation should be reclaimed + using CLAIM_DELEGATE_PREV as part of network partition recovery. + + o When the period of non-communicating is followed by a client + reboot, unreclaimed delegations should also be reclaimable by use + of CLAIM_DELEGATE_PREV as part of client reboot recovery. + + o When the period is terminated by a lease period elapsing without a + successful CLAIM_DELEGATE_PREV reclaim, and lease renewal is + occurring, the server may well conclude that unreclaimed + delegations have been abandoned and consider the situation as one + in which an implied DELEGPURGE should be assumed. + + + + + +Haynes & Noveck Standards Track [Page 143] + +RFC 7530 NFSv4 March 2015 + + + A server that supports a claim type of CLAIM_DELEGATE_PREV MUST + support the DELEGPURGE operation, and similarly, a server that + supports DELEGPURGE MUST support CLAIM_DELEGATE_PREV. A server that + does not support CLAIM_DELEGATE_PREV MUST return NFS4ERR_NOTSUPP if + the client attempts to use that feature or performs a DELEGPURGE + operation. + + Support for a claim type of CLAIM_DELEGATE_PREV is often referred to + as providing for "client-persistent delegations" in that they allow + the use of persistent storage on the client to store data written by + the client, even across a client restart. It should be noted that, + with the optional exception noted below, this feature requires + persistent storage to be used on the client and does not add to + persistent storage requirements on the server. + + One good way to think about client-persistent delegations is that for + the most part, they function like "courtesy locks", with special + semantic adjustments to allow them to be retained across a client + restart, which cause all other sorts of locks to be freed. Such + locks are generally not retained across a server restart. The one + exception is the case of simultaneous failure of the client and + server and is discussed below. + + When the server indicates support of CLAIM_DELEGATE_PREV (implicitly) + by returning NFS_OK to DELEGPURGE, a client with a write delegation + can use write-back caching for data to be written to the server, + deferring the write-back until such time as the delegation is + recalled, possibly after intervening client restarts. Similarly, + when the server indicates support of CLAIM_DELEGATE_PREV, a client + with a read delegation and an open-for-write subordinate to that + delegation may be sure of the integrity of its persistently cached + copy of the file after a client restart without specific verification + of the change attribute. + + When the server reboots or restarts, delegations are reclaimed (using + the OPEN operation with CLAIM_PREVIOUS) in a similar fashion to + byte-range locks and share reservations. However, there is a slight + semantic difference. In the normal case, if the server decides that + a delegation should not be granted, it performs the requested action + (e.g., OPEN) without granting any delegation. For reclaim, the + server grants the delegation, but a special designation is applied so + that the client treats the delegation as having been granted but + recalled by the server. Because of this, the client has the duty to + + + + + + + + +Haynes & Noveck Standards Track [Page 144] + +RFC 7530 NFSv4 March 2015 + + + write all modified state to the server and then return the + delegation. This process of handling delegation reclaim reconciles + three principles of the NFSv4 protocol: + + o Upon reclaim, a client claiming resources assigned to it by an + earlier server instance must be granted those resources. + + o The server has unquestionable authority to determine whether + delegations are to be granted and, once granted, whether they are + to be continued. + + o The use of callbacks is not to be depended upon until the client + has proven its ability to receive them. + + When a client has more than a single open associated with a + delegation, state for those additional opens can be established using + OPEN operations of type CLAIM_DELEGATE_CUR. When these are used to + establish opens associated with reclaimed delegations, the server + MUST allow them when made within the grace period. + + Situations in which there is a series of client and server restarts + where there is no restart of both at the same time are dealt with via + a combination of CLAIM_DELEGATE_PREV and CLAIM_PREVIOUS reclaim + cycles. Persistent storage is needed only on the client. For each + server failure, a CLAIM_PREVIOUS reclaim cycle is done, while for + each client restart, a CLAIM_DELEGATE_PREV reclaim cycle is done. + + To deal with the possibility of simultaneous failure of client and + server (e.g., a data center power outage), the server MAY + persistently store delegation information so that it can respond to a + CLAIM_DELEGATE_PREV reclaim request that it receives from a + restarting client. This is the one case in which persistent + delegation state can be retained across a server restart. A server + is not required to store this information, but if it does do so, it + should do so for write delegations and for read delegations, during + the pendency of which (across multiple client and/or server + instances), some open-for-write was done as part of delegation. When + the space to persistently record such information is limited, the + server should recall delegations in this class in preference to + keeping them active without persistent storage recording. + + When a network partition occurs, delegations are subject to freeing + by the server when the lease renewal period expires. This is similar + to the behavior for locks and share reservations, and as for locks + and share reservations, it may be modified by support for "courtesy + locks" in which locks are not freed in the absence of a conflicting + lock request. Whereas for locks and share reservations the freeing + of locks will occur immediately upon the appearance of a conflicting + + + +Haynes & Noveck Standards Track [Page 145] + +RFC 7530 NFSv4 March 2015 + + + request, for delegations, the server MAY institute a period during + which conflicting requests are held off. Eventually, the occurrence + of a conflicting request from another client will cause revocation of + the delegation. + + A loss of the callback path (e.g., by a later network configuration + change) will have a similar effect in that it can also result in + revocation of a delegation. A recall request will fail, and + revocation of the delegation will result. + + A client normally finds out about revocation of a delegation when it + uses a stateid associated with a delegation and receives one of the + errors NFS4ERR_EXPIRED, NFS4ERR_BAD_STATEID, or NFS4ERR_ADMIN_REVOKED + (NFS4ERR_EXPIRED indicates that all lock state associated with the + client has been lost). It also may find out about delegation + revocation after a client reboot when it attempts to reclaim a + delegation and receives NFS4ERR_EXPIRED. Note that in the case of a + revoked OPEN_DELEGATE_WRITE delegation, there are issues because data + may have been modified by the client whose delegation is revoked and, + separately, by other clients. See Section 10.5.1 for a discussion of + such issues. Note also that when delegations are revoked, + information about the revoked delegation will be written by the + server to stable storage (as described in Section 9.6). This is done + to deal with the case in which a server reboots after revoking a + delegation but before the client holding the revoked delegation is + notified about the revocation. + + Note that when there is a loss of a delegation, due to a network + partition in which all locks associated with the lease are lost, the + client will also receive the error NFS4ERR_EXPIRED. This case can be + distinguished from other situations in which delegations are revoked + by seeing that the associated clientid becomes invalid so that + NFS4ERR_STALE_CLIENTID is returned when it is used. + + When NFS4ERR_EXPIRED is returned, the server MAY retain information + about the delegations held by the client, deleting those that are + invalidated by a conflicting request. Retaining such information + will allow the client to recover all non-invalidated delegations + using the claim type CLAIM_DELEGATE_PREV, once the + SETCLIENTID_CONFIRM is done to recover. Attempted recovery of a + delegation that the client has no record of, typically because they + were invalidated by conflicting requests, will result in the error + NFS4ERR_BAD_RECLAIM. Once a reclaim is attempted for all delegations + that the client held, it SHOULD do a DELEGPURGE to allow any + remaining server delegation information to be freed. + + + + + + +Haynes & Noveck Standards Track [Page 146] + +RFC 7530 NFSv4 March 2015 + + +10.3. Data Caching + + When applications share access to a set of files, they need to be + implemented so as to take account of the possibility of conflicting + access by another application. This is true whether the applications + in question execute on different clients or reside on the same + client. + + Share reservations and byte-range locks are the facilities the NFSv4 + protocol provides to allow applications to coordinate access by + providing mutual exclusion facilities. The NFSv4 protocol's data + caching must be implemented such that it does not invalidate the + assumptions that those using these facilities depend upon. + +10.3.1. Data Caching and OPENs + + In order to avoid invalidating the sharing assumptions that + applications rely on, NFSv4 clients should not provide cached data to + applications or modify it on behalf of an application when it would + not be valid to obtain or modify that same data via a READ or WRITE + operation. + + Furthermore, in the absence of open delegation (see Section 10.4), + two additional rules apply. Note that these rules are obeyed in + practice by many NFSv2 and NFSv3 clients. + + o First, cached data present on a client must be revalidated after + doing an OPEN. Revalidating means that the client fetches the + change attribute from the server, compares it with the cached + change attribute, and, if different, declares the cached data (as + well as the cached attributes) as invalid. This is to ensure that + the data for the OPENed file is still correctly reflected in the + client's cache. This validation must be done at least when the + client's OPEN operation includes DENY=WRITE or BOTH, thus + terminating a period in which other clients may have had the + opportunity to open the file with WRITE access. Clients may + choose to do the revalidation more often (such as at OPENs + specifying DENY=NONE) to parallel the NFSv3 protocol's practice + for the benefit of users assuming this degree of cache + revalidation. + + Since the change attribute is updated for data and metadata + modifications, some client implementers may be tempted to use the + time_modify attribute and not the change attribute to validate + cached data, so that metadata changes do not spuriously invalidate + clean data. The implementer is cautioned against this approach. + The change attribute is guaranteed to change for each update to + the file, whereas time_modify is guaranteed to change only at the + + + +Haynes & Noveck Standards Track [Page 147] + +RFC 7530 NFSv4 March 2015 + + + granularity of the time_delta attribute. Use by the client's data + cache validation logic of time_modify and not the change attribute + runs the risk of the client incorrectly marking stale data as + valid. + + o Second, modified data must be flushed to the server before closing + a file OPENed for write. This is complementary to the first rule. + If the data is not flushed at CLOSE, the revalidation done after + the client OPENs a file is unable to achieve its purpose. The + other aspect to flushing the data before close is that the data + must be committed to stable storage, at the server, before the + CLOSE operation is requested by the client. In the case of a + server reboot or restart and a CLOSEd file, it may not be possible + to retransmit the data to be written to the file -- hence, this + requirement. + +10.3.2. Data Caching and File Locking + + For those applications that choose to use file locking instead of + share reservations to exclude inconsistent file access, there is an + analogous set of constraints that apply to client-side data caching. + These rules are effective only if the file locking is used in a way + that matches in an equivalent way the actual READ and WRITE + operations executed. This is as opposed to file locking that is + based on pure convention. For example, it is possible to manipulate + a two-megabyte file by dividing the file into two one-megabyte + regions and protecting access to the two regions by file locks on + bytes zero and one. A lock for write on byte zero of the file would + represent the right to do READ and WRITE operations on the first + region. A lock for write on byte one of the file would represent the + right to do READ and WRITE operations on the second region. As long + as all applications manipulating the file obey this convention, they + will work on a local file system. However, they may not work with + the NFSv4 protocol unless clients refrain from data caching. + + The rules for data caching in the file locking environment are: + + o First, when a client obtains a file lock for a particular region, + the data cache corresponding to that region (if any cached data + exists) must be revalidated. If the change attribute indicates + that the file may have been updated since the cached data was + obtained, the client must flush or invalidate the cached data for + the newly locked region. A client might choose to invalidate all + of the non-modified cached data that it has for the file, but the + only requirement for correct operation is to invalidate all of the + data in the newly locked region. + + + + + +Haynes & Noveck Standards Track [Page 148] + +RFC 7530 NFSv4 March 2015 + + + o Second, before releasing a write lock for a region, all modified + data for that region must be flushed to the server. The modified + data must also be written to stable storage. + + Note that flushing data to the server and the invalidation of cached + data must reflect the actual byte ranges locked or unlocked. + Rounding these up or down to reflect client cache block boundaries + will cause problems if not carefully done. For example, writing a + modified block when only half of that block is within an area being + unlocked may cause invalid modification to the region outside the + unlocked area. This, in turn, may be part of a region locked by + another client. Clients can avoid this situation by synchronously + performing portions of WRITE operations that overlap that portion + (initial or final) that is not a full block. Similarly, invalidating + a locked area that is not an integral number of full buffer blocks + would require the client to read one or two partial blocks from the + server if the revalidation procedure shows that the data that the + client possesses may not be valid. + + The data that is written to the server as a prerequisite to the + unlocking of a region must be written, at the server, to stable + storage. The client may accomplish this either with synchronous + writes or by following asynchronous writes with a COMMIT operation. + This is required because retransmission of the modified data after a + server reboot might conflict with a lock held by another client. + + A client implementation may choose to accommodate applications that + use byte-range locking in non-standard ways (e.g., using a byte-range + lock as a global semaphore) by flushing to the server more data upon + a LOCKU than is covered by the locked range. This may include + modified data within files other than the one for which the unlocks + are being done. In such cases, the client must not interfere with + applications whose READs and WRITEs are being done only within the + bounds of record locks that the application holds. For example, an + application locks a single byte of a file and proceeds to write that + single byte. A client that chose to handle a LOCKU by flushing all + modified data to the server could validly write that single byte in + response to an unrelated unlock. However, it would not be valid to + write the entire block in which that single written byte was located + since it includes an area that is not locked and might be locked by + another client. Client implementations can avoid this problem by + dividing files with modified data into those for which all + modifications are done to areas covered by an appropriate byte-range + lock and those for which there are modifications not covered by a + byte-range lock. Any writes done for the former class of files must + not include areas not locked and thus not modified on the client. + + + + + +Haynes & Noveck Standards Track [Page 149] + +RFC 7530 NFSv4 March 2015 + + +10.3.3. Data Caching and Mandatory File Locking + + Client-side data caching needs to respect mandatory file locking when + it is in effect. The presence of mandatory file locking for a given + file is indicated when the client gets back NFS4ERR_LOCKED from a + READ or WRITE on a file it has an appropriate share reservation for. + When mandatory locking is in effect for a file, the client must check + for an appropriate file lock for data being read or written. If a + lock exists for the range being read or written, the client may + satisfy the request using the client's validated cache. If an + appropriate file lock is not held for the range of the READ or WRITE, + the READ or WRITE request must not be satisfied by the client's cache + and the request must be sent to the server for processing. When a + READ or WRITE request partially overlaps a locked region, the request + should be subdivided into multiple pieces with each region (locked or + not) treated appropriately. + +10.3.4. Data Caching and File Identity + + When clients cache data, the file data needs to be organized + according to the file system object to which the data belongs. For + NFSv3 clients, the typical practice has been to assume for the + purpose of caching that distinct filehandles represent distinct file + system objects. The client then has the choice to organize and + maintain the data cache on this basis. + + In the NFSv4 protocol, there is now the possibility of having + significant deviations from a "one filehandle per object" model, + because a filehandle may be constructed on the basis of the object's + pathname. Therefore, clients need a reliable method to determine if + two filehandles designate the same file system object. If clients + were simply to assume that all distinct filehandles denote distinct + objects and proceed to do data caching on this basis, caching + inconsistencies would arise between the distinct client-side objects + that mapped to the same server-side object. + + By providing a method to differentiate filehandles, the NFSv4 + protocol alleviates a potential functional regression in comparison + with the NFSv3 protocol. Without this method, caching + inconsistencies within the same client could occur, and this has not + been present in previous versions of the NFS protocol. Note that it + is possible to have such inconsistencies with applications executing + on multiple clients, but that is not the issue being addressed here. + + + + + + + + +Haynes & Noveck Standards Track [Page 150] + +RFC 7530 NFSv4 March 2015 + + + For the purposes of data caching, the following steps allow an NFSv4 + client to determine whether two distinct filehandles denote the same + server-side object: + + o If GETATTR directed to two filehandles returns different values of + the fsid attribute, then the filehandles represent distinct + objects. + + o If GETATTR for any file with an fsid that matches the fsid of the + two filehandles in question returns a unique_handles attribute + with a value of TRUE, then the two objects are distinct. + + o If GETATTR directed to the two filehandles does not return the + fileid attribute for both of the handles, then it cannot be + determined whether the two objects are the same. Therefore, + operations that depend on that knowledge (e.g., client-side data + caching) cannot be done reliably. Note that if GETATTR does not + return the fileid attribute for both filehandles, it will return + it for neither of the filehandles, since the fsid for both + filehandles is the same. + + o If GETATTR directed to the two filehandles returns different + values for the fileid attribute, then they are distinct objects. + + o Otherwise, they are the same object. + +10.4. Open Delegation + + When a file is being OPENed, the server may delegate further handling + of opens and closes for that file to the opening client. Any such + delegation is recallable, since the circumstances that allowed for + the delegation are subject to change. In particular, the server may + receive a conflicting OPEN from another client; the server must + recall the delegation before deciding whether the OPEN from the other + client may be granted. Making a delegation is up to the server, and + clients should not assume that any particular OPEN either will or + will not result in an open delegation. The following is a typical + set of conditions that servers might use in deciding whether OPEN + should be delegated: + + o The client must be able to respond to the server's callback + requests. The server will use the CB_NULL procedure for a test of + callback ability. + + o The client must have responded properly to previous recalls. + + o There must be no current open conflicting with the requested + delegation. + + + +Haynes & Noveck Standards Track [Page 151] + +RFC 7530 NFSv4 March 2015 + + + o There should be no current delegation that conflicts with the + delegation being requested. + + o The probability of future conflicting open requests should be low, + based on the recent history of the file. + + o The existence of any server-specific semantics of OPEN/CLOSE that + would make the required handling incompatible with the prescribed + handling that the delegated client would apply (see below). + + There are two types of open delegations: OPEN_DELEGATE_READ and + OPEN_DELEGATE_WRITE. An OPEN_DELEGATE_READ delegation allows a + client to handle, on its own, requests to open a file for reading + that do not deny read access to others. It MUST, however, continue + to send all requests to open a file for writing to the server. + Multiple OPEN_DELEGATE_READ delegations may be outstanding + simultaneously and do not conflict. An OPEN_DELEGATE_WRITE + delegation allows the client to handle, on its own, all opens. Only + one OPEN_DELEGATE_WRITE delegation may exist for a given file at a + given time, and it is inconsistent with any OPEN_DELEGATE_READ + delegations. + + When a single client holds an OPEN_DELEGATE_READ delegation, it is + assured that no other client may modify the contents or attributes of + the file. If more than one client holds an OPEN_DELEGATE_READ + delegation, then the contents and attributes of that file are not + allowed to change. When a client has an OPEN_DELEGATE_WRITE + delegation, it may modify the file data since no other client will be + accessing the file's data. The client holding an OPEN_DELEGATE_WRITE + delegation may only affect file attributes that are intimately + connected with the file data: size, time_modify, and change. + + When a client has an open delegation, it does not send OPENs or + CLOSEs to the server but updates the appropriate status internally. + For an OPEN_DELEGATE_READ delegation, opens that cannot be handled + locally (opens for write or that deny read access) must be sent to + the server. + + When an open delegation is made, the response to the OPEN contains an + open delegation structure that specifies the following: + + o the type of delegation (read or write) + + o space limitation information to control flushing of data on close + (OPEN_DELEGATE_WRITE delegation only; see Section 10.4.1) + + + + + + +Haynes & Noveck Standards Track [Page 152] + +RFC 7530 NFSv4 March 2015 + + + o an nfsace4 specifying read and write permissions + + o a stateid to represent the delegation for READ and WRITE + + The delegation stateid is separate and distinct from the stateid for + the OPEN proper. The standard stateid, unlike the delegation + stateid, is associated with a particular open-owner and will continue + to be valid after the delegation is recalled and the file remains + 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 + the basis of the following conditions. Any requirement for other + 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. + + o The access and deny bits for the request and the file, as + described in Section 9.9. + + o The read and write permissions, as determined below. + + The nfsace4 passed with delegation can be used to avoid frequent + ACCESS calls. The permission check should be as follows: + + o If the nfsace4 indicates that the open may be done, then it should + be granted without reference to the server. + + o If the nfsace4 indicates that the open may not be done, then an + ACCESS request must be sent to the server to obtain the definitive + answer. + + The server may return an nfsace4 that is more restrictive than the + actual ACL of the file. This includes an nfsace4 that specifies + denial of all access. Note that some common practices, such as + mapping the traditional user "root" to the user "nobody", may make it + incorrect to return the actual ACL of the file in the delegation + response. + + The use of delegation, together with various other forms of caching, + creates the possibility that no server authentication will ever be + performed for a given user since all of the user's requests might be + satisfied locally. Where the client is depending on the server for + authentication, the client should be sure authentication occurs for + each user by use of the ACCESS operation. This should be the case + even if an ACCESS operation would not be required otherwise. As + mentioned before, the server may enforce frequent authentication by + returning an nfsace4 denying all access with every open delegation. + + + + +Haynes & Noveck Standards Track [Page 153] + +RFC 7530 NFSv4 March 2015 + + +10.4.1. Open Delegation and Data Caching + + OPEN delegation allows much of the message overhead associated with + the opening and closing files to be eliminated. An open when an open + delegation is in effect does not require that a validation message be + sent to the server unless there exists a potential for conflict with + the requested share mode. The continued endurance of the + "OPEN_DELEGATE_READ delegation" provides a guarantee that no OPEN for + write and thus no write has occurred that did not originate from this + client. Similarly, when closing a file opened for write and if + OPEN_DELEGATE_WRITE delegation is in effect, the data written does + not have to be flushed to the server until the open delegation is + recalled. The continued endurance of the open delegation provides a + guarantee that no open and thus no read or write has been done by + another client. + + For the purposes of open delegation, READs and WRITEs done without an + OPEN (anonymous and READ bypass stateids) are treated as the + functional equivalents of a corresponding type of OPEN. READs and + WRITEs done with an anonymous stateid done by another client will + force the server to recall an OPEN_DELEGATE_WRITE delegation. A + WRITE with an anonymous stateid done by another client will force a + recall of OPEN_DELEGATE_READ delegations. The handling of a READ + bypass stateid is identical, except that a READ done with a READ + bypass stateid will not force a recall of an OPEN_DELEGATE_READ + delegation. + + With delegations, a client is able to avoid writing data to the + server when the CLOSE of a file is serviced. The file close system + call is the usual point at which the client is notified of a lack of + stable storage for the modified file data generated by the + application. At the close, file data is written to the server, and + through normal accounting the server is able to determine if the + available file system space for the data has been exceeded (i.e., the + server returns NFS4ERR_NOSPC or NFS4ERR_DQUOT). This accounting + includes quotas. The introduction of delegations requires that an + alternative method be in place for the same type of communication to + occur between client and server. + + In the delegation response, the server provides either the limit of + the size of the file or the number of modified blocks and associated + block size. The server must ensure that the client will be able to + flush to the server data of a size equal to that provided in the + original delegation. The server must make this assurance for all + outstanding delegations. Therefore, the server must be careful in + its management of available space for new or modified data, taking + into account available file system space and any applicable quotas. + The server can recall delegations as a result of managing the + + + +Haynes & Noveck Standards Track [Page 154] + +RFC 7530 NFSv4 March 2015 + + + available file system space. The client should abide by the server's + state space limits for delegations. If the client exceeds the stated + limits for the delegation, the server's behavior is undefined. + + Based on server conditions, quotas, or available file system space, + the server may grant OPEN_DELEGATE_WRITE delegations with very + restrictive space limitations. The limitations may be defined in a + way that will always force modified data to be flushed to the server + on close. + + With respect to authentication, flushing modified data to the server + after a CLOSE has occurred may be problematic. For example, the user + of the application may have logged off the client, and unexpired + authentication credentials may not be present. In this case, the + client may need to take special care to ensure that local unexpired + credentials will in fact be available. One way that this may be + accomplished is by tracking the expiration time of credentials and + flushing data well in advance of their expiration. + +10.4.2. Open Delegation and File Locks + + When a client holds an OPEN_DELEGATE_WRITE delegation, lock + operations may be performed locally. This includes those required + for mandatory file locking. This can be done since the delegation + implies that there can be no conflicting locks. Similarly, all of + the revalidations that would normally be associated with obtaining + locks and the flushing of data associated with the releasing of locks + need not be done. + + When a client holds an OPEN_DELEGATE_READ delegation, lock operations + are not performed locally. All lock operations, including those + requesting non-exclusive locks, are sent to the server for + resolution. + +10.4.3. Handling of CB_GETATTR + + The server needs to employ special handling for a GETATTR where the + target is a file that has an OPEN_DELEGATE_WRITE delegation in + effect. The reason for this is that the client holding the + OPEN_DELEGATE_WRITE delegation may have modified the data, and the + server needs to reflect this change to the second client that + submitted the GETATTR. Therefore, the client holding the + OPEN_DELEGATE_WRITE delegation needs to be interrogated. The server + will use the CB_GETATTR operation. The only attributes that the + server can reliably query via CB_GETATTR are size and change. + + + + + + +Haynes & Noveck Standards Track [Page 155] + +RFC 7530 NFSv4 March 2015 + + + Since CB_GETATTR is being used to satisfy another client's GETATTR + request, the server only needs to know if the client holding the + delegation has a modified version of the file. If the client's copy + of the delegated file is not modified (data or size), the server can + satisfy the second client's GETATTR request from the attributes + stored locally at the server. If the file is modified, the server + only needs to know about this modified state. If the server + determines that the file is currently modified, it will respond to + the second client's GETATTR as if the file had been modified locally + at the server. + + Since the form of the change attribute is determined by the server + and is opaque to the client, the client and server need to agree on a + method of communicating the modified state of the file. For the size + attribute, the client will report its current view of the file size. + For the change attribute, the handling is more involved. + + For the client, the following steps will be taken when receiving an + OPEN_DELEGATE_WRITE delegation: + + o The value of the change attribute will be obtained from the server + and cached. Let this value be represented by c. + + o The client will create a value greater than c that will be used + for communicating that modified data is held at the client. Let + this value be represented by d. + + o When the client is queried via CB_GETATTR for the change + attribute, it checks to see if it holds modified data. If the + file is modified, the value d is returned for the change attribute + value. If this file is not currently modified, the client returns + the value c for the change attribute. + + For simplicity of implementation, the client MAY for each CB_GETATTR + return the same value d. This is true even if, between successive + CB_GETATTR operations, the client again modifies in the file's data + or metadata in its cache. The client can return the same value + because the only requirement is that the client be able to indicate + to the server that the client holds modified data. Therefore, the + value of d may always be c + 1. + + While the change attribute is opaque to the client in the sense that + it has no idea what units of time, if any, the server is counting + change with, it is not opaque in that the client has to treat it as + an unsigned integer, and the server has to be able to see the results + of the client's changes to that integer. Therefore, the server MUST + encode the change attribute in network byte order when sending it to + the client. The client MUST decode it from network byte order to its + + + +Haynes & Noveck Standards Track [Page 156] + +RFC 7530 NFSv4 March 2015 + + + native order when receiving it, and the client MUST encode it in + network byte order when sending it to the server. For this reason, + the change attribute is defined as an unsigned integer rather than an + opaque array of bytes. + + For the server, the following steps will be taken when providing an + OPEN_DELEGATE_WRITE delegation: + + o Upon providing an OPEN_DELEGATE_WRITE delegation, the server will + cache a copy of the change attribute in the data structure it uses + to record the delegation. Let this value be represented by sc. + + o When a second client sends a GETATTR operation on the same file to + the server, the server obtains the change attribute from the first + client. Let this value be cc. + + o If the value cc is equal to sc, the file is not modified and the + server returns the current values for change, time_metadata, and + time_modify (for example) to the second client. + + o If the value cc is NOT equal to sc, the file is currently modified + at the first client and most likely will be modified at the server + at a future time. The server then uses its current time to + construct attribute values for time_metadata and time_modify. A + new value of sc, which we will call nsc, is computed by the + server, such that nsc >= sc + 1. The server then returns the + constructed time_metadata, time_modify, and nsc values to the + requester. The server replaces sc in the delegation record with + nsc. To prevent the possibility of time_modify, time_metadata, + and change from appearing to go backward (which would happen if + the client holding the delegation fails to write its modified data + to the server before the delegation is revoked or returned), the + server SHOULD update the file's metadata record with the + constructed attribute values. For reasons of reasonable + performance, committing the constructed attribute values to stable + storage is OPTIONAL. + + As discussed earlier in this section, the client MAY return the same + cc value on subsequent CB_GETATTR calls, even if the file was + modified in the client's cache yet again between successive + CB_GETATTR calls. Therefore, the server must assume that the file + has been modified yet again and MUST take care to ensure that the new + nsc it constructs and returns is greater than the previous nsc it + returned. An example implementation's delegation record would + satisfy this mandate by including a boolean field (let us call it + "modified") that is set to FALSE when the delegation is granted, and + an sc value set at the time of grant to the change attribute value. + The modified field would be set to TRUE the first time cc != sc and + + + +Haynes & Noveck Standards Track [Page 157] + +RFC 7530 NFSv4 March 2015 + + + would stay TRUE until the delegation is returned or revoked. The + processing for constructing nsc, time_modify, and time_metadata would + use this pseudo-code: + + if (!modified) { + do CB_GETATTR for change and size; + + if (cc != sc) + modified = TRUE; + } else { + do CB_GETATTR for size; + } + + if (modified) { + sc = sc + 1; + time_modify = time_metadata = current_time; + update sc, time_modify, time_metadata into file's metadata; + } + + This would return to the client (that sent GETATTR) the attributes it + requested but would make sure that size comes from what CB_GETATTR + returned. The server would not update the file's metadata with the + client's modified size. + + In the case that the file attribute size is different than the + server's current value, the server treats this as a modification + regardless of the value of the change attribute retrieved via + CB_GETATTR and responds to the second client as in the last step. + + This methodology resolves issues of clock differences between + client and server and other scenarios where the use of CB_GETATTR + breaks down. + + It should be noted that the server is under no obligation to use + CB_GETATTR; therefore, the server MAY simply recall the delegation to + avoid its use. + +10.4.4. Recall of Open Delegation + + The following events necessitate the recall of an open delegation: + + o Potentially conflicting OPEN request (or READ/WRITE done with + "special" stateid) + + o SETATTR issued by another client + + + + + + +Haynes & Noveck Standards Track [Page 158] + +RFC 7530 NFSv4 March 2015 + + + o REMOVE request for the file + + o RENAME request for the file as either source or target of the + RENAME + + Whether a RENAME of a directory in the path leading to the file + results in the recall of an open delegation depends on the semantics + of the server file system. If that file system denies such RENAMEs + when a file is open, the recall must be performed to determine + whether the file in question is, in fact, open. + + In addition to the situations above, the server may choose to recall + open delegations at any time if resource constraints make it + advisable to do so. Clients should always be prepared for the + possibility of a recall. + + When a client receives a recall for an open delegation, it needs to + update state on the server before returning the delegation. These + same updates must be done whenever a client chooses to return a + delegation voluntarily. The following items of state need to be + dealt with: + + o If the file associated with the delegation is no longer open and + no previous CLOSE operation has been sent to the server, a CLOSE + operation must be sent to the server. + + o If a file has other open references at the client, then OPEN + operations must be sent to the server. The appropriate stateids + will be provided by the server for subsequent use by the client + since the delegation stateid will not longer be valid. These OPEN + requests are done with the claim type of CLAIM_DELEGATE_CUR. This + will allow the presentation of the delegation stateid so that the + client can establish the appropriate rights to perform the OPEN. + (See Section 16.16 for details.) + + o If there are granted file locks, the corresponding LOCK operations + need to be performed. This applies to the OPEN_DELEGATE_WRITE + delegation case only. + + o For an OPEN_DELEGATE_WRITE delegation, if at the time of the + recall the file is not open for write, all modified data for the + file must be flushed to the server. If the delegation had not + existed, the client would have done this data flush before the + CLOSE operation. + + o For an OPEN_DELEGATE_WRITE delegation, when a file is still open + at the time of the recall, any modified data for the file needs to + be flushed to the server. + + + +Haynes & Noveck Standards Track [Page 159] + +RFC 7530 NFSv4 March 2015 + + + o With the OPEN_DELEGATE_WRITE delegation in place, it is possible + that the file was truncated during the duration of the delegation. + For example, the truncation could have occurred as a result of an + OPEN UNCHECKED4 with a size attribute value of zero. Therefore, + if a truncation of the file has occurred and this operation has + not been propagated to the server, the truncation must occur + before any modified data is written to the server. + + In the case of an OPEN_DELEGATE_WRITE delegation, file locking + imposes some additional requirements. To precisely maintain the + associated invariant, it is required to flush any modified data in + any region for which a write lock was released while the + OPEN_DELEGATE_WRITE delegation was in effect. However, because the + OPEN_DELEGATE_WRITE delegation implies no other locking by other + clients, a simpler implementation is to flush all modified data for + the file (as described just above) if any write lock has been + released while the OPEN_DELEGATE_WRITE delegation was in effect. + + An implementation need not wait until delegation recall (or deciding + to voluntarily return a delegation) to perform any of the above + actions, if implementation considerations (e.g., resource + availability constraints) make that desirable. Generally, however, + the fact that the actual open state of the file may continue to + change makes it not worthwhile to send information about opens and + closes to the server, except as part of delegation return. Only in + the case of closing the open that resulted in obtaining the + delegation would clients be likely to do this early, since, in that + case, the close once done will not be undone. Regardless of the + client's choices on scheduling these actions, all must be performed + before the delegation is returned, including (when applicable) the + close that corresponds to the open that resulted in the delegation. + These actions can be performed either in previous requests or in + previous operations in the same COMPOUND request. + +10.4.5. OPEN Delegation Race with CB_RECALL + + The server informs the client of a recall via a CB_RECALL. A race + case that may develop is when the delegation is immediately recalled + before the COMPOUND that established the delegation is returned to + the client. As the CB_RECALL provides both a stateid and a + filehandle for which the client has no mapping, it cannot honor the + recall attempt. At this point, the client has two choices: either do + not respond or respond with NFS4ERR_BADHANDLE. If it does not + respond, then it runs the risk of the server deciding to not grant it + further delegations. + + + + + + +Haynes & Noveck Standards Track [Page 160] + +RFC 7530 NFSv4 March 2015 + + + If instead it does reply with NFS4ERR_BADHANDLE, then both the client + and the server might be able to detect that a race condition is + occurring. The client can keep a list of pending delegations. When + it receives a CB_RECALL for an unknown delegation, it can cache the + stateid and filehandle on a list of pending recalls. When it is + provided with a delegation, it would only use it if it was not on the + pending recall list. Upon the next CB_RECALL, it could immediately + return the delegation. + + In turn, the server can keep track of when it issues a delegation and + assume that if a client responds to the CB_RECALL with an + NFS4ERR_BADHANDLE, then the client has yet to receive the delegation. + The server SHOULD give the client a reasonable time both to get this + delegation and to return it before revoking the delegation. Unlike a + failed callback path, the server should periodically probe the client + with CB_RECALL to see if it has received the delegation and is ready + to return it. + + When the server finally determines that enough time has elapsed, it + SHOULD revoke the delegation and it SHOULD NOT revoke the lease. + During this extended recall process, the server SHOULD be renewing + the client lease. The intent here is that the client not pay too + onerous a burden for a condition caused by the server. + +10.4.6. Clients That Fail to Honor Delegation Recalls + + A client may fail to respond to a recall for various reasons, such as + a failure of the callback path from the server to the client. The + client may be unaware of a failure in the callback path. This lack + of awareness could result in the client finding out long after the + failure that its delegation has been revoked, and another client has + modified the data for which the client had a delegation. This is + especially a problem for the client that held an OPEN_DELEGATE_WRITE + delegation. + + The server also has a dilemma in that the client that fails to + respond to the recall might also be sending other NFS requests, + including those that renew the lease before the lease expires. + Without returning an error for those lease-renewing operations, the + server leads the client to believe that the delegation it has is + in force. + + + + + + + + + + +Haynes & Noveck Standards Track [Page 161] + +RFC 7530 NFSv4 March 2015 + + + This difficulty is solved by the following rules: + + o When the callback path is down, the server MUST NOT revoke the + delegation if one of the following occurs: + + * The client has issued a RENEW operation, and the server has + returned an NFS4ERR_CB_PATH_DOWN error. The server MUST renew + the lease for any byte-range locks and share reservations the + client has that the server has known about (as opposed to those + locks and share reservations the client has established but not + yet sent to the server, due to the delegation). The server + SHOULD give the client a reasonable time to return its + delegations to the server before revoking the client's + delegations. + + * The client has not issued a RENEW operation for some period of + time after the server attempted to recall the delegation. This + period of time MUST NOT be less than the value of the + lease_time attribute. + + o When the client holds a delegation, it cannot rely on operations, + except for RENEW, that take a stateid, to renew delegation leases + across callback path failures. The client that wants to keep + delegations in force across callback path failures must use RENEW + to do so. + +10.4.7. Delegation Revocation + + At the point a delegation is revoked, if there are associated opens + on the client, the applications holding these opens need to be + notified. This notification usually occurs by returning errors for + READ/WRITE operations or when a close is attempted for the open file. + + If no opens exist for the file at the point the delegation is + revoked, then notification of the revocation is unnecessary. + However, if there is modified data present at the client for the + file, the user of the application should be notified. Unfortunately, + it may not be possible to notify the user since active applications + may not be present at the client. See Section 10.5.1 for additional + details. + +10.5. Data Caching and Revocation + + When locks and delegations are revoked, the assumptions upon which + successful caching depend are no longer guaranteed. For any locks or + share reservations that have been revoked, the corresponding owner + needs to be notified. This notification includes applications with a + file open that has a corresponding delegation that has been revoked. + + + +Haynes & Noveck Standards Track [Page 162] + +RFC 7530 NFSv4 March 2015 + + + Cached data associated with the revocation must be removed from the + client. In the case of modified data existing in the client's cache, + that data must be removed from the client without it being written to + the server. As mentioned, the assumptions made by the client are no + longer valid at the point when a lock or delegation has been revoked. + For example, another client may have been granted a conflicting lock + after the revocation of the lock at the first client. Therefore, the + data within the lock range may have been modified by the other + client. Obviously, the first client is unable to guarantee to the + application what has occurred to the file in the case of revocation. + + Notification to a lock-owner will in many cases consist of simply + returning an error on the next and all subsequent READs/WRITEs to the + open file or on the close. Where the methods available to a client + make such notification impossible because errors for certain + operations may not be returned, more drastic action, such as signals + or process termination, may be appropriate. The justification for + this is that an invariant on which an application depends may be + violated. Depending on how errors are typically treated for the + client operating environment, further levels of notification, + including logging, console messages, and GUI pop-ups, may be + appropriate. + +10.5.1. Revocation Recovery for Write Open Delegation + + Revocation recovery for an OPEN_DELEGATE_WRITE delegation poses the + special issue of modified data in the client cache while the file is + not open. In this situation, any client that does not flush modified + data to the server on each close must ensure that the user receives + appropriate notification of the failure as a result of the + revocation. Since such situations may require human action to + correct problems, notification schemes in which the appropriate user + or administrator is notified may be necessary. Logging and console + messages are typical examples. + + If there is modified data on the client, it must not be flushed + normally to the server. A client may attempt to provide a copy of + the file data as modified during the delegation under a different + name in the file system namespace to ease recovery. Note that when + the client can determine that the file has not been modified by any + other client, or when the client has a complete cached copy of the + file in question, such a saved copy of the client's view of the file + may be of particular value for recovery. In other cases, recovery + using a copy of the file, based partially on the client's cached data + and partially on the server copy as modified by other clients, will + be anything but straightforward, so clients may avoid saving file + contents in these situations or mark the results specially to warn + users of possible problems. + + + +Haynes & Noveck Standards Track [Page 163] + +RFC 7530 NFSv4 March 2015 + + + The saving of such modified data in delegation revocation situations + may be limited to files of a certain size or might be used only when + sufficient disk space is available within the target file system. + Such saving may also be restricted to situations when the client has + sufficient buffering resources to keep the cached copy available + until it is properly stored to the target file system. + +10.6. Attribute Caching + + The attributes discussed in this section do not include named + attributes. Individual named attributes are analogous to files, and + caching of the data for these needs to be handled just as data + caching is for regular files. Similarly, LOOKUP results from an + OPENATTR directory are to be cached on the same basis as any other + pathnames and similarly for directory contents. + + Clients may cache file attributes obtained from the server and use + them to avoid subsequent GETATTR requests. This cache is write + through caching in that any modifications to the file attributes are + always done by means of requests to the server, which means the + modifications should not be done locally and should not be cached. + Exceptions to this are modifications to attributes that are + intimately connected with data caching. Therefore, extending a file + by writing data to the local data cache is reflected immediately in + the size as seen on the client without this change being immediately + reflected on the server. Normally, such changes are not propagated + directly to the server, but when the modified data is flushed to the + server, analogous attribute changes are made on the server. When + open delegation is in effect, the modified attributes may be returned + to the server in the response to a CB_GETATTR call. + + The result of local caching of attributes is that the attribute + caches maintained on individual clients will not be coherent. + Changes made in one order on the server may be seen in a different + order on one client and in a third order on a different client. + + The typical file system application programming interfaces do not + provide means to atomically modify or interrogate attributes for + multiple files at the same time. The following rules provide an + environment where the potential incoherency mentioned above can be + reasonably managed. These rules are derived from the practice of + previous NFS protocols. + + o All attributes for a given file (per-fsid attributes excepted) are + cached as a unit at the client so that no non-serializability can + arise within the context of a single file. + + + + + +Haynes & Noveck Standards Track [Page 164] + +RFC 7530 NFSv4 March 2015 + + + o An upper time boundary is maintained on how long a client cache + entry can be kept without being refreshed from the server. + + o When operations are performed that modify attributes at the + server, the updated attribute set is requested as part of the + containing RPC. This includes directory operations that update + attributes indirectly. This is accomplished by following the + modifying operation with a GETATTR operation and then using the + results of the GETATTR to update the client's cached attributes. + + Note that if the full set of attributes to be cached is requested by + READDIR, the results can be cached by the client on the same basis as + attributes obtained via GETATTR. + + A client may validate its cached version of attributes for a file by + only fetching both the change and time_access attributes and assuming + that if the change attribute has the same value as it did when the + attributes were cached, then no attributes other than time_access + have changed. The time_access attribute is also fetched because many + servers operate in environments where the operation that updates + change does not update time_access. For example, POSIX file + semantics do not update access time when a file is modified by the + write system call. Therefore, the client that wants a current + time_access value should fetch it with change during the attribute + cache validation processing and update its cached time_access. + + The client may maintain a cache of modified attributes for those + attributes intimately connected with data of modified regular files + (size, time_modify, and change). Other than those three attributes, + the client MUST NOT maintain a cache of modified attributes. + Instead, attribute changes are immediately sent to the server. + + In some operating environments, the equivalent to time_access is + expected to be implicitly updated by each read of the content of the + file object. If an NFS client is caching the content of a file + object, whether it is a regular file, directory, or symbolic link, + the client SHOULD NOT update the time_access attribute (via SETATTR + or a small READ or READDIR request) on the server with each read that + is satisfied from cache. The reason is that this can defeat the + performance benefits of caching content, especially since an explicit + SETATTR of time_access may alter the change attribute on the server. + If the change attribute changes, clients that are caching the content + will think the content has changed and will re-read unmodified data + from the server. Nor is the client encouraged to maintain a modified + version of time_access in its cache, since this would mean that the + client either will eventually have to write the access time to the + server with bad performance effects or would never update the + server's time_access, thereby resulting in a situation where an + + + +Haynes & Noveck Standards Track [Page 165] + +RFC 7530 NFSv4 March 2015 + + + application that caches access time between a close and open of the + same file observes the access time oscillating between the past and + present. The time_access attribute always means the time of last + access to a file by a READ that was satisfied by the server. This + way, clients will tend to see only time_access changes that go + forward in time. + +10.7. Data and Metadata Caching and Memory-Mapped Files + + Some operating environments include the capability for an application + to map a file's content into the application's address space. Each + time the application accesses a memory location that corresponds to a + block that has not been loaded into the address space, a page fault + occurs and the file is read (or if the block does not exist in the + file, the block is allocated and then instantiated in the + application's address space). + + As long as each memory-mapped access to the file requires a page + fault, the relevant attributes of the file that are used to detect + access and modification (time_access, time_metadata, time_modify, and + change) will be updated. However, in many operating environments, + when page faults are not required, these attributes will not be + updated on reads or updates to the file via memory access (regardless + of whether the file is a local file or is being accessed remotely). + A client or server MAY fail to update attributes of a file that is + being accessed via memory-mapped I/O. This has several implications: + + o If there is an application on the server that has memory mapped a + file that a client is also accessing, the client may not be able + to get a consistent value of the change attribute to determine + whether its cache is stale or not. A server that knows that the + file is memory mapped could always pessimistically return updated + values for change so as to force the application to always get the + most up-to-date data and metadata for the file. However, due to + the negative performance implications of this, such behavior is + OPTIONAL. + + o If the memory-mapped file is not being modified on the server and + instead is just being read by an application via the memory-mapped + interface, the client will not see an updated time_access + attribute. However, in many operating environments, neither will + any process running on the server. Thus, NFS clients are at no + disadvantage with respect to local processes. + + o If there is another client that is memory mapping the file and if + that client is holding an OPEN_DELEGATE_WRITE delegation, the same + set of issues as discussed in the previous two bullet items apply. + So, when a server does a CB_GETATTR to a file that the client has + + + +Haynes & Noveck Standards Track [Page 166] + +RFC 7530 NFSv4 March 2015 + + + modified in its cache, the response from CB_GETATTR will not + necessarily be accurate. As discussed earlier, the client's + obligation is to report that the file has been modified since the + delegation was granted, not whether it has been modified again + between successive CB_GETATTR calls, and the server MUST assume + that any file the client has modified in cache has been modified + again between successive CB_GETATTR calls. Depending on the + nature of the client's memory management system, this weak + obligation may not be possible. A client MAY return stale + information in CB_GETATTR whenever the file is memory mapped. + + o The mixture of memory mapping and file locking on the same file is + problematic. Consider the following scenario, where the page size + on each client is 8192 bytes. + + * Client A memory maps first page (8192 bytes) of file X. + + * Client B memory maps first page (8192 bytes) of file X. + + * Client A write locks first 4096 bytes. + + * Client B write locks second 4096 bytes. + + * Client A, via a STORE instruction, modifies part of its locked + region. + + * Simultaneous to client A, client B issues a STORE on part of + its locked region. + + Here, the challenge is for each client to resynchronize to get a + correct view of the first page. In many operating environments, the + virtual memory management systems on each client only know a page is + modified, not that a subset of the page corresponding to the + respective lock regions has been modified. So it is not possible for + each client to do the right thing, which is to only write to the + server that portion of the page that is locked. For example, if + client A simply writes out the page, and then client B writes out the + page, client A's data is lost. + + Moreover, if mandatory locking is enabled on the file, then we have a + different problem. When clients A and B issue the STORE + instructions, the resulting page faults require a byte-range lock on + the entire page. Each client then tries to extend their locked range + to the entire page, which results in a deadlock. + + Communicating the NFS4ERR_DEADLOCK error to a STORE instruction is + difficult at best. + + + + +Haynes & Noveck Standards Track [Page 167] + +RFC 7530 NFSv4 March 2015 + + + If a client is locking the entire memory-mapped file, there is no + problem with advisory or mandatory byte-range locking, at least until + the client unlocks a region in the middle of the file. + + Given the above issues, the following are permitted: + + o Clients and servers MAY deny memory mapping a file they know there + are byte-range locks for. + + o Clients and servers MAY deny a byte-range lock on a file they know + is memory mapped. + + o A client MAY deny memory mapping a file that it knows requires + mandatory locking for I/O. If mandatory locking is enabled after + the file is opened and mapped, the client MAY deny the application + further access to its mapped file. + +10.8. Name Caching + + The results of LOOKUP and READDIR operations may be cached to avoid + the cost of subsequent LOOKUP operations. Just as in the case of + attribute caching, inconsistencies may arise among the various client + caches. To mitigate the effects of these inconsistencies and given + the context of typical file system APIs, an upper time boundary is + maintained on how long a client name cache entry can be kept without + verifying that the entry has not been made invalid by a directory + change operation performed by another client. + + When a client is not making changes to a directory for which there + exist name cache entries, the client needs to periodically fetch + attributes for that directory to ensure that it is not being + modified. After determining that no modification has occurred, the + expiration time for the associated name cache entries may be updated + to be the current time plus the name cache staleness bound. + + When a client is making changes to a given directory, it needs to + determine whether there have been changes made to the directory by + other clients. It does this by using the change attribute as + reported before and after the directory operation in the associated + change_info4 value returned for the operation. The server is able to + communicate to the client whether the change_info4 data is provided + atomically with respect to the directory operation. If the change + values are provided atomically, the client is then able to compare + the pre-operation change value with the change value in the client's + name cache. If the comparison indicates that the directory was + updated by another client, the name cache associated with the + modified directory is purged from the client. If the comparison + indicates no modification, the name cache can be updated on the + + + +Haynes & Noveck Standards Track [Page 168] + +RFC 7530 NFSv4 March 2015 + + + client to reflect the directory operation and the associated timeout + extended. The post-operation change value needs to be saved as the + basis for future change_info4 comparisons. + + As demonstrated by the scenario above, name caching requires that the + client revalidate name cache data by inspecting the change attribute + of a directory at the point when the name cache item was cached. + This requires that the server update the change attribute for + directories when the contents of the corresponding directory are + modified. For a client to use the change_info4 information + appropriately and correctly, the server must report the pre- and + post-operation change attribute values atomically. When the server + is unable to report the before and after values atomically with + respect to the directory operation, the server must indicate that + fact in the change_info4 return value. When the information is not + atomically reported, the client should not assume that other clients + have not changed the directory. + +10.9. Directory Caching + + The results of READDIR operations may be used to avoid subsequent + READDIR operations. Just as in the cases of attribute and name + caching, inconsistencies may arise among the various client caches. + To mitigate the effects of these inconsistencies, and given the + context of typical file system APIs, the following rules should be + followed: + + o Cached READDIR information for a directory that is not obtained in + a single READDIR operation must always be a consistent snapshot of + directory contents. This is determined by using a GETATTR before + the first READDIR and after the last READDIR that contributes to + the cache. + + o An upper time boundary is maintained to indicate the length of + time a directory cache entry is considered valid before the client + must revalidate the cached information. + + The revalidation technique parallels that discussed in the case of + name caching. When the client is not changing the directory in + question, checking the change attribute of the directory with GETATTR + is adequate. The lifetime of the cache entry can be extended at + these checkpoints. When a client is modifying the directory, the + client needs to use the change_info4 data to determine whether there + are other clients modifying the directory. If it is determined that + no other client modifications are occurring, the client may update + its directory cache to reflect its own changes. + + + + + +Haynes & Noveck Standards Track [Page 169] + +RFC 7530 NFSv4 March 2015 + + + As demonstrated previously, directory caching requires that the + client revalidate directory cache data by inspecting the change + attribute of a directory at the point when the directory was cached. + This requires that the server update the change attribute for + directories when the contents of the corresponding directory are + modified. For a client to use the change_info4 information + appropriately and correctly, the server must report the pre- and + post-operation change attribute values atomically. When the server + is unable to report the before and after values atomically with + respect to the directory operation, the server must indicate that + fact in the change_info4 return value. When the information is not + atomically reported, the client should not assume that other clients + have not changed the directory. + +11. Minor Versioning + + To address the requirement of an NFS protocol that can evolve as the + need arises, the NFSv4 protocol contains the rules and framework to + allow for future minor changes or versioning. + + The base assumption with respect to minor versioning is that any + future accepted minor version must follow the IETF process and be + documented in a Standards Track RFC. Therefore, each minor version + number will correspond to an RFC. Minor version 0 of the NFSv4 + protocol is represented by this RFC. The COMPOUND and CB_COMPOUND + procedures support the encoding of the minor version being requested + by the client. + + Future minor versions will extend, rather than replace, the XDR for + the preceding minor version, as had been done in moving from NFSv2 to + NFSv3 and from NFSv3 to NFSv4.0. + + Specification of detailed rules for the construction of minor + versions will be addressed in documents defining early minor versions + or, more desirably, in an RFC establishing a versioning framework for + NFSv4 as a whole. + +12. Internationalization + +12.1. Introduction + + Internationalization is a complex topic with its own set of + terminology (see [RFC6365]). The topic is made more complex in + NFSv4.0 by the tangled history and state of NFS implementations. + This section describes what we might call "NFSv4.0 + internationalization" (i.e., internationalization as implemented by + existing clients and servers) as the basis upon which NFSv4.0 clients + may implement internationalization support. + + + +Haynes & Noveck Standards Track [Page 170] + +RFC 7530 NFSv4 March 2015 + + + This section is based on the behavior of existing implementations. + Note that the behaviors described are each demonstrated by a + combination of an NFSv4 server implementation proper and a + server-side physical file system. It is common for servers and + physical file systems to be configurable as to the behavior shown. + In the discussion below, each configuration that shows different + behavior is considered separately. + + Note that in this section, the key words "MUST", "SHOULD", and "MAY" + retain their normal meanings. However, in deriving this + specification from implementation patterns, we document below how the + normative terms used derive from the behavior of existing + implementations, in those situations in which existing implementation + behavior patterns can be determined. + + o Behavior implemented by all existing clients or servers is + described using "MUST", since new implementations need to follow + existing ones to be assured of interoperability. While it is + possible that different behavior might be workable, we have found + no case where this seems reasonable. + + The converse holds for "MUST NOT": if a type of behavior poses + interoperability problems, it MUST NOT be implemented by any + existing clients or servers. + + o Behavior implemented by most existing clients or servers, where + that behavior is more desirable than any alternative, is described + using "SHOULD", since new implementations need to follow that + existing practice unless there are strong reasons to do otherwise. + + The converse holds for "SHOULD NOT". + + o Behavior implemented by some, but not all, existing clients or + servers is described using "MAY", indicating that new + implementations have a choice as to whether they will behave in + that way. Thus, new implementations will have the same + flexibility that existing ones do. + + o Behavior implemented by all existing clients or servers, so far as + is known -- but where there remains some uncertainty as to details + -- is described using "should". Such cases primarily concern + details of error returns. New implementations should follow + existing practice even though such situations generally do not + affect interoperability. + + There are also cases in which certain server behaviors, while not + known to exist, cannot be reliably determined not to exist. In part, + this is a consequence of the long period of time that has elapsed + + + +Haynes & Noveck Standards Track [Page 171] + +RFC 7530 NFSv4 March 2015 + + + since the publication of [RFC3530], resulting in a situation in which + those involved in the implementation may no longer be involved in or + aware of working group activities. + + In the case of possible server behavior that is neither known to + exist nor known not to exist, we use "SHOULD NOT" and "MUST NOT" as + follows, and similarly for "SHOULD" and "MUST". + + o In some cases, the potential behavior is not known to exist but is + of such a nature that, if it were in fact implemented, + interoperability difficulties would be expected and reported, + giving us cause to conclude that the potential behavior is not + implemented. For such behavior, we use "MUST NOT". Similarly, we + use "MUST" to apply to the contrary behavior. + + o In other cases, potential behavior is not known to exist but the + behavior, while undesirable, is not of such a nature that we are + able to draw any conclusions about its potential existence. In + such cases, we use "SHOULD NOT". Similarly, we use "SHOULD" to + apply to the contrary behavior. + + In the case of a "MAY", "SHOULD", or "SHOULD NOT" that applies to + servers, clients need to be aware that there are servers that may or + may not take the specified action, and they need to be prepared for + either eventuality. + +12.2. Limitations on Internationalization-Related Processing in the + NFSv4 Context + + There are a number of noteworthy circumstances that limit the degree + to which internationalization-related processing can be made + universal with regard to NFSv4 clients and servers: + + o The NFSv4 client is part of an extensive set of client-side + software components whose design and internal interfaces are not + within the IETF's purview, limiting the degree to which a + particular character encoding may be made standard. + + o Server-side handling of file component names is typically + implemented within a server-side physical file system, whose + handling of character encoding and normalization is not + specifiable by the IETF. + + o Typical implementation patterns in UNIX systems result in the + NFSv4 client having no knowledge of the character encoding being + used, which may even vary between processes on the same client + system. + + + + +Haynes & Noveck Standards Track [Page 172] + +RFC 7530 NFSv4 March 2015 + + + o Users may need access to files stored previously with non-UTF-8 + encodings, or with UTF-8 encodings that do not match any + particular normalization form. + +12.3. Summary of Server Behavior Types + + As mentioned in Section 12.6, servers MAY reject component name + strings that are not valid UTF-8. This leads to a number of types of + valid server behavior, as outlined below. When these are combined + with the valid normalization-related behaviors as described in + Section 12.4, this leads to the combined behaviors outlined below. + + o Servers that limit file component names to UTF-8 strings exist + with normalization-related handling as described in Section 12.4. + These are best described as "UTF-8-only servers". + + o Servers that do not limit file component names to UTF-8 strings + are very common and are necessary to deal with clients/ + applications not oriented to the use of UTF-8. Such servers + ignore normalization-related issues, and there is no way for them + to implement either normalization or representation-independent + lookups. These are best described as "UTF-8-unaware servers", + since they treat file component names as uninterpreted strings of + bytes and have no knowledge of the characters represented. See + Section 12.7 for details. + + o It is possible for a server to allow component names that are not + valid UTF-8, while still being aware of the structure of UTF-8 + strings. Such servers could implement either normalization or + representation-independent lookups but apply those techniques only + to valid UTF-8 strings. Such servers are not common, but it is + possible to configure at least one known server to have this + behavior. This behavior SHOULD NOT be used due to the possibility + that a filename using one character set may, by coincidence, + have the appearance of a UTF-8 filename; the results of UTF-8 + normalization or representation-independent lookups are + unlikely to be correct in all cases with respect to the other + character set. + +12.4. String Encoding + + Strings that potentially contain characters outside the ASCII range + [RFC20] are generally represented in NFSv4 using the UTF-8 encoding + [RFC3629] of Unicode [UNICODE]. See [RFC3629] for precise encoding + and decoding rules. + + + + + + +Haynes & Noveck Standards Track [Page 173] + +RFC 7530 NFSv4 March 2015 + + + Some details of the protocol treatment depend on the type of string: + + o For strings that are component names, the preferred encoding for + any non-ASCII characters is the UTF-8 representation of Unicode. + + In many cases, clients have no knowledge of the encoding being + used, with the encoding done at the user level under the control + of a per-process locale specification. As a result, it may be + impossible for the NFSv4 client to enforce the use of UTF-8. The + use of non-UTF-8 encodings can be problematic, since it may + interfere with access to files stored using other forms of name + encoding. Also, normalization-related processing (see + Section 12.5) of a string not encoded in UTF-8 could result in + inappropriate name modification or aliasing. In cases in which + one has a non-UTF-8 encoded name that accidentally conforms to + UTF-8 rules, substitution of canonically equivalent strings can + change the non-UTF-8 encoded name drastically. + + The kinds of modification and aliasing mentioned here can lead to + both false negatives and false positives, depending on the strings + in question, which can result in security issues such as elevation + of privilege and denial of service (see [RFC6943] for further + discussion). + + o For strings based on domain names, non-ASCII characters MUST be + represented using the UTF-8 encoding of Unicode, and additional + string format restrictions apply. See Section 12.6 for details. + + o The contents of symbolic links (of type linktext4 in the XDR) MUST + be treated as opaque data by NFSv4 servers. Although UTF-8 + encoding is often used, it need not be. In this respect, the + contents of symbolic links are like the contents of regular files + in that their encoding is not within the scope of this + specification. + + o For other sorts of strings, any non-ASCII characters SHOULD be + represented using the UTF-8 encoding of Unicode. + +12.5. Normalization + + The client and server operating environments may differ in their + policies and operational methods with respect to character + normalization (see [UNICODE] for a discussion of normalization + forms). This difference may also exist between applications on the + same client. This adds to the difficulty of providing a single + normalization policy for the protocol that allows for maximal + interoperability. This issue is similar to the issues of character + case where the server may or may not support case-insensitive + + + +Haynes & Noveck Standards Track [Page 174] + +RFC 7530 NFSv4 March 2015 + + + filename matching and may or may not preserve the character case when + storing filenames. The protocol does not mandate a particular + behavior but allows for a range of useful behaviors. + + The NFSv4 protocol does not mandate the use of a particular + normalization form at this time. A subsequent minor version of the + NFSv4 protocol might specify a particular normalization form. + Therefore, the server and client can expect that they may receive + unnormalized characters within protocol requests and responses. If + the operating environment requires normalization, then the + implementation will need to normalize the various UTF-8 encoded + strings within the protocol before presenting the information to an + application (at the client) or local file system (at the server). + + Server implementations MAY normalize filenames to conform to a + particular normalization form before using the resulting string when + looking up or creating a file. Servers MAY also perform + normalization-insensitive string comparisons without modifying the + names to match a particular normalization form. Except in cases in + which component names are excluded from normalization-related + handling because they are not valid UTF-8 strings, a server MUST make + the same choice (as to whether to normalize or not, the target form + of normalization, and whether to do normalization-insensitive string + comparisons) in the same way for all accesses to a particular file + system. Servers SHOULD NOT reject a filename because it does not + conform to a particular normalization form, as this may deny access + to clients that use a different normalization form. + +12.6. Types with Processing Defined by Other Internet Areas + + There are two types of strings that NFSv4 deals with that are based + on domain names. Processing of such strings is defined by other + Internet standards, and hence the processing behavior for such + strings should be consistent across all server operating systems and + server file systems. + + These are as follows: + + o Server names as they appear in the fs_locations attribute. Note + that for most purposes, such server names will only be sent by the + server to the client. The exception is the use of the + fs_locations attribute in a VERIFY or NVERIFY operation. + + o Principal suffixes that are used to denote sets of users and + groups, and are in the form of domain names. + + + + + + +Haynes & Noveck Standards Track [Page 175] + +RFC 7530 NFSv4 March 2015 + + + The general rules for handling all of these domain-related strings + are similar and independent of the role of the sender or receiver as + client or server, although the consequences of failure to obey these + rules may be different for client or server. The server can report + errors when it is sent invalid strings, whereas the client will + simply ignore invalid string or use a default value in their place. + + The string sent SHOULD be in the form of one or more U-labels as + defined by [RFC5890]. If that is impractical, it can instead be in + the form of one or more LDH labels [RFC5890] or a UTF-8 domain name + that contains labels that are not properly formatted U-labels. The + receiver needs to be able to accept domain and server names in any of + the formats allowed. The server MUST reject, using the error + NFS4ERR_INVAL, a string that is not valid UTF-8, or that contains an + ASCII label that is not a valid LDH label, or that contains an + XN-label (begins with "xn--") for which the characters after "xn--" + are not valid output of the Punycode algorithm [RFC3492]. + + When a domain string is part of id@domain or group@domain, there are + two possible approaches: + + 1. The server treats the domain string as a series of U-labels. In + cases where the domain string is a series of A-labels or + Non-Reserved LDH (NR-LDH) labels, it converts them to U-labels + using the Punycode algorithm [RFC3492]. In cases where the + domain string is a series of other sorts of LDH labels, the + server can use the ToUnicode function defined in [RFC3490] to + convert the string to a series of labels that generally conform + to the U-label syntax. In cases where the domain string is a + UTF-8 string that contains non-U-labels, the server can attempt + to use the ToASCII function defined in [RFC3490] and then the + ToUnicode function on the string to convert it to a series of + labels that generally conform to the U-label syntax. As a + result, the domain string returned within a user id on a GETATTR + may not match that sent when the user id is set using SETATTR, + although when this happens, the domain will be in the form that + generally conforms to the U-label syntax. + + 2. The server does not attempt to treat the domain string as a + series of U-labels; specifically, it does not map a domain string + that is not a U-label into a U-label using the methods described + above. As a result, the domain string returned on a GETATTR of + the user id MUST be the same as that used when setting the + user id by the SETATTR. + + A server SHOULD use the first method. + + + + + +Haynes & Noveck Standards Track [Page 176] + +RFC 7530 NFSv4 March 2015 + + + For VERIFY and NVERIFY, additional string processing requirements + apply to verification of the owner and owner_group attributes; see + Section 5.9. + +12.7. Errors Related to UTF-8 + + Where the client sends an invalid UTF-8 string, the server MAY return + an NFS4ERR_INVAL error. This includes cases in which inappropriate + prefixes are detected and where the count includes trailing bytes + that do not constitute a full Universal Multiple-Octet Coded + Character Set (UCS) character. + + Requirements for server handling of component names that are not + valid UTF-8, when a server does not return NFS4ERR_INVAL in response + to receiving them, are described in Section 12.8. + + Where the string supplied by the client is not rejected with + NFS4ERR_INVAL but contains characters that are not supported by the + server as a value for that string (e.g., names containing slashes, or + characters that do not fit into 16 bits when converted from UTF-8 to + a Unicode codepoint), the server should return an NFS4ERR_BADCHAR + error. + + Where a UTF-8 string is used as a filename, and the file system, + while supporting all of the characters within the name, does not + allow that particular name to be used, the server should return the + error NFS4ERR_BADNAME. This includes such situations as file system + prohibitions of "." and ".." as filenames for certain operations, and + similar constraints. + +12.8. Servers That Accept File Component Names That Are Not Valid UTF-8 + Strings + + As stated previously, servers MAY accept, on all or on some subset of + the physical file systems exported, component names that are not + valid UTF-8 strings. A typical pattern is for a server to use + UTF-8-unaware physical file systems that treat component names as + uninterpreted strings of bytes, rather than having any awareness of + the character set being used. + + Such servers SHOULD NOT change the stored representation of component + names from those received on the wire and SHOULD use an octet-by- + octet comparison of component name strings to determine equivalence + (as opposed to any broader notion of string comparison). This is + because the server has no knowledge of the character encoding being + used. + + + + + +Haynes & Noveck Standards Track [Page 177] + +RFC 7530 NFSv4 March 2015 + + + Nonetheless, when such a server uses a broader notion of string + equivalence than what is recommended in the preceding paragraph, the + following considerations apply: + + o Outside of 7-bit ASCII, string processing that changes string + contents is usually specific to a character set and hence is + generally unsafe when the character set is unknown. This + processing could change the filename in an unexpected fashion, + rendering the file inaccessible to the application or client that + created or renamed the file and to others expecting the original + filename. Hence, such processing should not be performed, because + doing so is likely to result in incorrect string modification or + aliasing. + + o Unicode normalization is particularly dangerous, as such + processing assumes that the string is UTF-8. When that assumption + is false because a different character set was used to create the + filename, normalization may corrupt the filename with respect to + that character set, rendering the file inaccessible to the + application that created it and others expecting the original + filename. Hence, Unicode normalization SHOULD NOT be performed, + because it may cause incorrect string modification or aliasing. + + When the above recommendations are not followed, the resulting string + modification and aliasing can lead to both false negatives and false + positives, depending on the strings in question, which can result in + security issues such as elevation of privilege and denial of service + (see [RFC6943] for further discussion). + +13. Error Values + + NFS error numbers are assigned to failed operations within a COMPOUND + or CB_COMPOUND request. A COMPOUND request contains a number of NFS + operations that have their results encoded in sequence in a COMPOUND + reply. The results of successful operations will consist of an + NFS4_OK status followed by the encoded results of the operation. If + an NFS operation fails, an error status will be entered in the reply, + and the COMPOUND request will be terminated. + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 178] + +RFC 7530 NFSv4 March 2015 + + +13.1. Error Definitions + + +-----------------------------+--------+-------------------+ + | Error | Number | Description | + +-----------------------------+--------+-------------------+ + | NFS4_OK | 0 | Section 13.1.3.1 | + | NFS4ERR_ACCESS | 13 | Section 13.1.6.1 | + | NFS4ERR_ADMIN_REVOKED | 10047 | Section 13.1.5.1 | + | NFS4ERR_ATTRNOTSUPP | 10032 | Section 13.1.11.1 | + | NFS4ERR_BADCHAR | 10040 | Section 13.1.7.1 | + | NFS4ERR_BADHANDLE | 10001 | Section 13.1.2.1 | + | NFS4ERR_BADNAME | 10041 | Section 13.1.7.2 | + | NFS4ERR_BADOWNER | 10039 | Section 13.1.11.2 | + | NFS4ERR_BADTYPE | 10007 | Section 13.1.4.1 | + | NFS4ERR_BADXDR | 10036 | Section 13.1.1.1 | + | NFS4ERR_BAD_COOKIE | 10003 | Section 13.1.1.2 | + | NFS4ERR_BAD_RANGE | 10042 | Section 13.1.8.1 | + | NFS4ERR_BAD_SEQID | 10026 | Section 13.1.8.2 | + | NFS4ERR_BAD_STATEID | 10025 | Section 13.1.5.2 | + | NFS4ERR_CB_PATH_DOWN | 10048 | Section 13.1.12.1 | + | NFS4ERR_CLID_INUSE | 10017 | Section 13.1.10.1 | + | NFS4ERR_DEADLOCK | 10045 | Section 13.1.8.3 | + | NFS4ERR_DELAY | 10008 | Section 13.1.1.3 | + | NFS4ERR_DENIED | 10010 | Section 13.1.8.4 | + | NFS4ERR_DQUOT | 69 | Section 13.1.4.2 | + | NFS4ERR_EXIST | 17 | Section 13.1.4.3 | + | NFS4ERR_EXPIRED | 10011 | Section 13.1.5.3 | + | NFS4ERR_FBIG | 27 | Section 13.1.4.4 | + | NFS4ERR_FHEXPIRED | 10014 | Section 13.1.2.2 | + | NFS4ERR_FILE_OPEN | 10046 | Section 13.1.4.5 | + | NFS4ERR_GRACE | 10013 | Section 13.1.9.1 | + | NFS4ERR_INVAL | 22 | Section 13.1.1.4 | + | NFS4ERR_IO | 5 | Section 13.1.4.6 | + | NFS4ERR_ISDIR | 21 | Section 13.1.2.3 | + | NFS4ERR_LEASE_MOVED | 10031 | Section 13.1.5.4 | + | NFS4ERR_LOCKED | 10012 | Section 13.1.8.5 | + | NFS4ERR_LOCKS_HELD | 10037 | Section 13.1.8.6 | + | NFS4ERR_LOCK_NOTSUPP | 10043 | Section 13.1.8.7 | + | NFS4ERR_LOCK_RANGE | 10028 | Section 13.1.8.8 | + | NFS4ERR_MINOR_VERS_MISMATCH | 10021 | Section 13.1.3.2 | + | NFS4ERR_MLINK | 31 | Section 13.1.4.7 | + | NFS4ERR_MOVED | 10019 | Section 13.1.2.4 | + | NFS4ERR_NAMETOOLONG | 63 | Section 13.1.7.3 | + | NFS4ERR_NOENT | 2 | Section 13.1.4.8 | + | NFS4ERR_NOFILEHANDLE | 10020 | Section 13.1.2.5 | + | NFS4ERR_NOSPC | 28 | Section 13.1.4.9 | + | NFS4ERR_NOTDIR | 20 | Section 13.1.2.6 | + | NFS4ERR_NOTEMPTY | 66 | Section 13.1.4.10 | + + + +Haynes & Noveck Standards Track [Page 179] + +RFC 7530 NFSv4 March 2015 + + + | NFS4ERR_NOTSUPP | 10004 | Section 13.1.1.5 | + | NFS4ERR_NOT_SAME | 10027 | Section 13.1.11.3 | + | NFS4ERR_NO_GRACE | 10033 | Section 13.1.9.2 | + | NFS4ERR_NXIO | 6 | Section 13.1.4.11 | + | NFS4ERR_OLD_STATEID | 10024 | Section 13.1.5.5 | + | NFS4ERR_OPENMODE | 10038 | Section 13.1.8.9 | + | NFS4ERR_OP_ILLEGAL | 10044 | Section 13.1.3.3 | + | NFS4ERR_PERM | 1 | Section 13.1.6.2 | + | NFS4ERR_RECLAIM_BAD | 10034 | Section 13.1.9.3 | + | NFS4ERR_RECLAIM_CONFLICT | 10035 | Section 13.1.9.4 | + | NFS4ERR_RESOURCE | 10018 | Section 13.1.3.4 | + | NFS4ERR_RESTOREFH | 10030 | Section 13.1.4.12 | + | NFS4ERR_ROFS | 30 | Section 13.1.4.13 | + | NFS4ERR_SAME | 10009 | Section 13.1.11.4 | + | NFS4ERR_SERVERFAULT | 10006 | Section 13.1.1.6 | + | NFS4ERR_SHARE_DENIED | 10015 | Section 13.1.8.10 | + | NFS4ERR_STALE | 70 | Section 13.1.2.7 | + | NFS4ERR_STALE_CLIENTID | 10022 | Section 13.1.10.2 | + | NFS4ERR_STALE_STATEID | 10023 | Section 13.1.5.6 | + | NFS4ERR_SYMLINK | 10029 | Section 13.1.2.8 | + | NFS4ERR_TOOSMALL | 10005 | Section 13.1.1.7 | + | NFS4ERR_WRONGSEC | 10016 | Section 13.1.6.3 | + | NFS4ERR_XDEV | 18 | Section 13.1.4.14 | + +-----------------------------+--------+-------------------+ + + Table 6: Protocol Error Definitions + +13.1.1. General Errors + + This section deals with errors that are applicable to a broad set of + different purposes. + +13.1.1.1. NFS4ERR_BADXDR (Error Code 10036) + + The arguments for this operation do not match those specified in the + XDR definition. This includes situations in which the request ends + before all the arguments have been seen. Note that this error + applies when fixed enumerations (these include booleans) have a value + within the input stream that is not valid for the enum. A replier + may pre-parse all operations for a COMPOUND procedure before doing + any operation execution and return RPC-level XDR errors in that case. + +13.1.1.2. NFS4ERR_BAD_COOKIE (Error Code 10003) + + This error is used for operations that provide a set of information + indexed by some quantity provided by the client or cookie sent by the + server for an earlier invocation. Where the value cannot be used for + its intended purpose, this error results. + + + +Haynes & Noveck Standards Track [Page 180] + +RFC 7530 NFSv4 March 2015 + + +13.1.1.3. NFS4ERR_DELAY (Error Code 10008) + + For any of a number of reasons, the replier could not process this + operation in what was deemed a reasonable time. The client should + wait and then try the request with a new RPC transaction ID. + + The following are two examples of what might lead to this situation: + + o A server that supports hierarchical storage receives a request to + process a file that had been migrated. + + o An operation requires a delegation recall to proceed, and waiting + for this delegation recall makes processing this request in a + timely fashion impossible. + +13.1.1.4. NFS4ERR_INVAL (Error Code 22) + + The arguments for this operation are not valid for some reason, even + though they do match those specified in the XDR definition for the + request. + +13.1.1.5. NFS4ERR_NOTSUPP (Error Code 10004) + + The operation is not supported, either because the operation is an + OPTIONAL one and is not supported by this server or because the + operation MUST NOT be implemented in the current minor version. + +13.1.1.6. NFS4ERR_SERVERFAULT (Error Code 10006) + + An error that does not map to any of the specific legal NFSv4 + protocol error values occurred on the server. The client should + translate this into an appropriate error. UNIX clients may choose to + translate this to EIO. + +13.1.1.7. NFS4ERR_TOOSMALL (Error Code 10005) + + This error is used where an operation returns a variable amount of + data, with a limit specified by the client. Where the data returned + cannot be fitted within the limit specified by the client, this error + results. + +13.1.2. Filehandle Errors + + These errors deal with the situation in which the current or saved + filehandle, or the filehandle passed to PUTFH intended to become the + current filehandle, is invalid in some way. This includes situations + in which the filehandle is a valid filehandle in general but is not + of the appropriate object type for the current operation. + + + +Haynes & Noveck Standards Track [Page 181] + +RFC 7530 NFSv4 March 2015 + + + Where the error description indicates a problem with the current or + saved filehandle, it is to be understood that filehandles are only + checked for the condition if they are implicit arguments of the + operation in question. + +13.1.2.1. NFS4ERR_BADHANDLE (Error Code 10001) + + This error is generated for an illegal NFS filehandle for the current + server. The current filehandle failed internal consistency checks. + Once accepted as valid (by PUTFH), no subsequent status change can + cause the filehandle to generate this error. + +13.1.2.2. NFS4ERR_FHEXPIRED (Error Code 10014) + + A current or saved filehandle that is an argument to the current + operation is volatile and has expired at the server. + +13.1.2.3. NFS4ERR_ISDIR (Error Code 21) + + The current or saved filehandle designates a directory when the + current operation does not allow a directory to be accepted as the + target of this operation. + +13.1.2.4. NFS4ERR_MOVED (Error Code 10019) + + The file system that contains the current filehandle object is not + present at the server. It may have been relocated or migrated to + another server, or may have never been present. The client may + obtain the new file system location by obtaining the "fs_locations" + attribute for the current filehandle. For further discussion, refer + to Section 8. + +13.1.2.5. NFS4ERR_NOFILEHANDLE (Error Code 10020) + + The logical current or saved filehandle value is required by the + current operation and is not set. This may be a result of a + malformed COMPOUND operation (i.e., no PUTFH or PUTROOTFH before an + operation that requires that the current filehandle be set). + +13.1.2.6. NFS4ERR_NOTDIR (Error Code 20) + + The current (or saved) filehandle designates an object that is not a + directory for an operation in which a directory is required. + + + + + + + + +Haynes & Noveck Standards Track [Page 182] + +RFC 7530 NFSv4 March 2015 + + +13.1.2.7. NFS4ERR_STALE (Error Code 70) + + The current or saved filehandle value designating an argument to the + current operation is invalid. The file system object referred to by + that filehandle no longer exists, or access to it has been revoked. + +13.1.2.8. NFS4ERR_SYMLINK (Error Code 10029) + + The current filehandle designates a symbolic link when the current + operation does not allow a symbolic link as the target. + +13.1.3. Compound Structure Errors + + This section deals with errors that relate to the overall structure + of a COMPOUND request (by which we mean to include both COMPOUND and + CB_COMPOUND), rather than to particular operations. + + There are a number of basic constraints on the operations that may + appear in a COMPOUND request. + +13.1.3.1. NFS_OK (Error Code 0) + + NFS_OK indicates that the operation completed successfully, in that + all of the constituent operations completed without error. + +13.1.3.2. NFS4ERR_MINOR_VERS_MISMATCH (Error Code 10021) + + The minor version specified is not one that the current listener + supports. This value is returned in the overall status for the + COMPOUND procedure but is not associated with a specific operation, + since the results must specify a result count of zero. + +13.1.3.3. NFS4ERR_OP_ILLEGAL (Error Code 10044) + + The operation code is not a valid one for the current COMPOUND + procedure. The opcode in the result stream matched with this error + is the ILLEGAL value, although the value that appears in the request + stream may be different. Where an illegal value appears and the + replier pre-parses all operations for a COMPOUND procedure before + doing any operation execution, an RPC-level XDR error may be returned + in this case. + + + + + + + + + + +Haynes & Noveck Standards Track [Page 183] + +RFC 7530 NFSv4 March 2015 + + +13.1.3.4. NFS4ERR_RESOURCE (Error Code 10018) + + For the processing of the COMPOUND procedure, the server may exhaust + available resources and cannot continue processing operations within + the COMPOUND procedure. This error will be returned from the server + in those instances of resource exhaustion related to the processing + of the COMPOUND procedure. + +13.1.4. File System Errors + + These errors describe situations that occurred in the underlying file + system implementation rather than in the protocol or any NFSv4.x + feature. + +13.1.4.1. NFS4ERR_BADTYPE (Error Code 10007) + + An attempt was made to create an object with an inappropriate type + specified to CREATE. This may be because the type is undefined; + because it is a type not supported by the server; or because it is a + type for which create is not intended, such as a regular file or + named attribute, for which OPEN is used to do the file creation. + +13.1.4.2. NFS4ERR_DQUOT (Error Code 69) + + The resource (quota) hard limit has been exceeded. The user's + resource limit on the server has been exceeded. + +13.1.4.3. NFS4ERR_EXIST (Error Code 17) + + A file system object of the specified target name (when creating, + renaming, or linking) already exists. + +13.1.4.4. NFS4ERR_FBIG (Error Code 27) + + The file system object is too large. The operation would have caused + a file system object to grow beyond the server's limit. + +13.1.4.5. NFS4ERR_FILE_OPEN (Error Code 10046) + + The operation is not allowed because a file system object involved in + the operation is currently open. Servers may, but are not required + to, disallow linking to, removing, or renaming open file system + objects. + +13.1.4.6. NFS4ERR_IO (Error Code 5) + + This indicates that an I/O error occurred for which the file system + was unable to provide recovery. + + + +Haynes & Noveck Standards Track [Page 184] + +RFC 7530 NFSv4 March 2015 + + +13.1.4.7. NFS4ERR_MLINK (Error Code 31) + + The request would have caused the server's limit for the number of + hard links a file system object may have to be exceeded. + +13.1.4.8. NFS4ERR_NOENT (Error Code 2) + + This indicates no such file or directory. The file system object + referenced by the name specified does not exist. + +13.1.4.9. NFS4ERR_NOSPC (Error Code 28) + + This indicates no space left on the device. The operation would have + caused the server's file system to exceed its limit. + +13.1.4.10. NFS4ERR_NOTEMPTY (Error Code 66) + + An attempt was made to remove a directory that was not empty. + +13.1.4.11. NFS4ERR_NXIO (Error Code 6) + + This indicates an I/O error. There is no such device or address. + +13.1.4.12. NFS4ERR_RESTOREFH (Error Code 10030) + + The RESTOREFH operation does not have a saved filehandle (identified + by SAVEFH) to operate upon. + +13.1.4.13. NFS4ERR_ROFS (Error Code 30) + + This indicates a read-only file system. A modifying operation was + attempted on a read-only file system. + +13.1.4.14. NFS4ERR_XDEV (Error Code 18) + + This indicates an attempt to do an operation, such as linking, that + inappropriately crosses a boundary. For example, this may be due to + a boundary between: + + o File systems (where the fsids are different). + + o Different named attribute directories, or between a named + attribute directory and an ordinary directory. + + o Regions of a file system that the file system implementation + treats as separate (for example, for space accounting purposes), + and where cross-connection between the regions is not allowed. + + + + +Haynes & Noveck Standards Track [Page 185] + +RFC 7530 NFSv4 March 2015 + + +13.1.5. State Management Errors + + These errors indicate problems with the stateid (or one of the + stateids) passed to a given operation. This includes situations in + which the stateid is invalid, as well as situations in which the + stateid is valid but designates revoked locking state. Depending on + the operation, the stateid, when valid, may designate opens, + byte-range locks, or file delegations. + +13.1.5.1. NFS4ERR_ADMIN_REVOKED (Error Code 10047) + + A stateid designates locking state of any type that has been revoked + due to administrative interaction, possibly while the lease is valid, + or because a delegation was revoked because of failure to return it, + while the lease was valid. + +13.1.5.2. NFS4ERR_BAD_STATEID (Error Code 10025) + + A stateid generated by the current server instance was used that + either: + + o Does not designate any locking state (either current or + superseded) for a current (state-owner, file) pair. + + o Designates locking state that was freed after lease expiration but + without any lease cancellation, as may happen in the handling of + "courtesy locks". + +13.1.5.3. NFS4ERR_EXPIRED (Error Code 10011) + + A stateid or clientid designates locking state of any type that has + been revoked or released due to cancellation of the client's lease, + either immediately upon lease expiration, or following a later + request for a conflicting lock. + +13.1.5.4. NFS4ERR_LEASE_MOVED (Error Code 10031) + + A lease being renewed is associated with a file system that has been + migrated to a new server. + +13.1.5.5. NFS4ERR_OLD_STATEID (Error Code 10024) + + A stateid is provided with a seqid value that is not the most + current. + +13.1.5.6. NFS4ERR_STALE_STATEID (Error Code 10023) + + A stateid generated by an earlier server instance was used. + + + +Haynes & Noveck Standards Track [Page 186] + +RFC 7530 NFSv4 March 2015 + + +13.1.6. Security Errors + + These are the various permission-related errors in NFSv4. + +13.1.6.1. NFS4ERR_ACCESS (Error Code 13) + + This indicates permission denied. The caller does not have the + correct permission to perform the requested operation. Contrast this + with NFS4ERR_PERM (Section 13.1.6.2), which restricts itself to owner + or privileged user permission failures. + +13.1.6.2. NFS4ERR_PERM (Error Code 1) + + This indicates that the requester is not the owner. The operation + was not allowed because the caller is neither a privileged user + (root) nor the owner of the target of the operation. + +13.1.6.3. NFS4ERR_WRONGSEC (Error Code 10016) + + This indicates that the security mechanism being used by the client + for the operation does not match the server's security policy. The + client should change the security mechanism being used and re-send + the operation. SECINFO can be used to determine the appropriate + mechanism. + +13.1.7. Name Errors + + Names in NFSv4 are UTF-8 strings. When the strings are not of length + zero, the error NFS4ERR_INVAL results. When they are not valid + UTF-8, the error NFS4ERR_INVAL also results, but servers may + accommodate file systems with different character formats and not + return this error. Besides this, there are a number of other errors + to indicate specific problems with names. + +13.1.7.1. NFS4ERR_BADCHAR (Error Code 10040) + + A UTF-8 string contains a character that is not supported by the + server in the context in which it is being used. + +13.1.7.2. NFS4ERR_BADNAME (Error Code 10041) + + A name string in a request consisted of valid UTF-8 characters + supported by the server, but the name is not supported by the server + as a valid name for current operation. An example might be creating + a file or directory named ".." on a server whose file system uses + that name for links to parent directories. + + + + + +Haynes & Noveck Standards Track [Page 187] + +RFC 7530 NFSv4 March 2015 + + + This error should not be returned due to a normalization issue in a + string. When a file system keeps names in a particular normalization + form, it is the server's responsibility to do the appropriate + normalization, rather than rejecting the name. + +13.1.7.3. NFS4ERR_NAMETOOLONG (Error Code 63) + + This is returned when the filename in an operation exceeds the + server's implementation limit. + +13.1.8. Locking Errors + + This section deals with errors related to locking -- both share + reservations and byte-range locking. It does not deal with errors + specific to the process of reclaiming locks. Those are dealt with in + the next section. + +13.1.8.1. NFS4ERR_BAD_RANGE (Error Code 10042) + + The range for a LOCK, LOCKT, or LOCKU operation is not appropriate to + the allowable range of offsets for the server. For example, this + error results when a server that only supports 32-bit ranges receives + a range that cannot be handled by that server. (See + Section 16.10.4.) + +13.1.8.2. NFS4ERR_BAD_SEQID (Error Code 10026) + + The sequence number (seqid) in a locking request is neither the next + expected number nor the last number processed. + +13.1.8.3. NFS4ERR_DEADLOCK (Error Code 10045) + + The server has been able to determine a file locking deadlock + condition for a blocking lock request. + +13.1.8.4. NFS4ERR_DENIED (Error Code 10010) + + An attempt to lock a file is denied. Since this may be a temporary + condition, the client is encouraged to re-send the lock request until + the lock is accepted. See Section 9.4 for a discussion of the + re-send. + + + + + + + + + + +Haynes & Noveck Standards Track [Page 188] + +RFC 7530 NFSv4 March 2015 + + +13.1.8.5. NFS4ERR_LOCKED (Error Code 10012) + + A READ or WRITE operation was attempted on a file where there was a + conflict between the I/O and an existing lock: + + o There is a share reservation inconsistent with the I/O being done. + + o The range to be read or written intersects an existing mandatory + byte-range lock. + +13.1.8.6. NFS4ERR_LOCKS_HELD (Error Code 10037) + + An operation was prevented by the unexpected presence of locks. + +13.1.8.7. NFS4ERR_LOCK_NOTSUPP (Error Code 10043) + + A locking request was attempted that would require the upgrade or + downgrade of a lock range already held by the owner when the server + does not support atomic upgrade or downgrade of locks. + +13.1.8.8. NFS4ERR_LOCK_RANGE (Error Code 10028) + + A lock request is operating on a range that partially overlaps a + currently held lock for the current lock-owner and does not precisely + match a single such lock, where the server does not support this type + of request and thus does not implement POSIX locking semantics + [fcntl]. See Sections 16.10.5, 16.11.5, and 16.12.5 for a discussion + of how this applies to LOCK, LOCKT, and LOCKU, respectively. + +13.1.8.9. NFS4ERR_OPENMODE (Error Code 10038) + + The client attempted a READ, WRITE, LOCK, or other operation not + sanctioned by the stateid passed (e.g., writing to a file opened only + for read). + +13.1.8.10. NFS4ERR_SHARE_DENIED (Error Code 10015) + + An attempt to OPEN a file with a share reservation has failed because + of a share conflict. + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 189] + +RFC 7530 NFSv4 March 2015 + + +13.1.9. Reclaim Errors + + These errors relate to the process of reclaiming locks after a server + restart. + +13.1.9.1. NFS4ERR_GRACE (Error Code 10013) + + The server is in its recovery or grace period, which should at least + match the lease period of the server. A locking request other than a + reclaim could not be granted during that period. + +13.1.9.2. NFS4ERR_NO_GRACE (Error Code 10033) + + The server cannot guarantee that it has not granted state to another + client that may conflict with this client's state. No further + reclaims from this client will succeed. + +13.1.9.3. NFS4ERR_RECLAIM_BAD (Error Code 10034) + + The server cannot guarantee that it has not granted state to another + client that may conflict with the requested state. However, this + applies only to the state requested in this call; further reclaims + may succeed. + + Unlike NFS4ERR_RECLAIM_CONFLICT, this can occur between correctly + functioning clients and servers: the "edge condition" scenarios + described in Section 9.6.3.4 leave only the server knowing whether + the client's locks are still valid, and NFS4ERR_RECLAIM_BAD is the + server's way of informing the client that they are not. + +13.1.9.4. NFS4ERR_RECLAIM_CONFLICT (Error Code 10035) + + The reclaim attempted by the client conflicts with a lock already + held by another client. Unlike NFS4ERR_RECLAIM_BAD, this can only + occur if one of the clients misbehaved. + + + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 190] + +RFC 7530 NFSv4 March 2015 + + +13.1.10. Client Management Errors + + This section deals with errors associated with requests used to + create and manage client IDs. + +13.1.10.1. NFS4ERR_CLID_INUSE (Error Code 10017) + + The SETCLIENTID operation has found that a clientid is already in use + by another client. + +13.1.10.2. NFS4ERR_STALE_CLIENTID (Error Code 10022) + + A client ID not recognized by the server was used in a locking or + SETCLIENTID_CONFIRM request. + +13.1.11. Attribute Handling Errors + + This section deals with errors specific to attribute handling within + NFSv4. + +13.1.11.1. NFS4ERR_ATTRNOTSUPP (Error Code 10032) + + An attribute specified is not supported by the server. This error + MUST NOT be returned by the GETATTR operation. + +13.1.11.2. NFS4ERR_BADOWNER (Error Code 10039) + + This error is returned when an owner or owner_group attribute value + or the who field of an ace within an ACL attribute value cannot be + translated to a local representation. + +13.1.11.3. NFS4ERR_NOT_SAME (Error Code 10027) + + This error is returned by the VERIFY operation to signify that the + attributes compared were not the same as those provided in the + client's request. + +13.1.11.4. NFS4ERR_SAME (Error Code 10009) + + This error is returned by the NVERIFY operation to signify that the + attributes compared were the same as those provided in the client's + request. + +13.1.12. Miscellaneous Errors + +13.1.12.1. NFS4ERR_CB_PATH_DOWN (Error Code 10048) + + There is a problem contacting the client via the callback path. + + + +Haynes & Noveck Standards Track [Page 191] + +RFC 7530 NFSv4 March 2015 + + +13.2. Operations and Their Valid Errors + + This section contains a table that gives the valid error returns for + each protocol operation. The error code NFS4_OK (indicating no + error) is not listed but should be understood to be returnable by all + operations except ILLEGAL. + + +---------------------+---------------------------------------------+ + | Operation | Errors | + +---------------------+---------------------------------------------+ + | ACCESS | NFS4ERR_ACCESS, NFS4ERR_BADHANDLE, | + | | NFS4ERR_BADXDR, NFS4ERR_DELAY, | + | | NFS4ERR_FHEXPIRED, NFS4ERR_INVAL, | + | | NFS4ERR_IO, NFS4ERR_MOVED, | + | | NFS4ERR_NOFILEHANDLE, NFS4ERR_RESOURCE, | + | | NFS4ERR_SERVERFAULT, NFS4ERR_STALE | + | | | + | CLOSE | NFS4ERR_ADMIN_REVOKED, NFS4ERR_BADHANDLE, | + | | NFS4ERR_BAD_SEQID, NFS4ERR_BAD_STATEID, | + | | NFS4ERR_BADXDR, NFS4ERR_DELAY, | + | | NFS4ERR_EXPIRED, NFS4ERR_FHEXPIRED, | + | | NFS4ERR_INVAL, NFS4ERR_ISDIR, | + | | NFS4ERR_LEASE_MOVED, NFS4ERR_LOCKS_HELD, | + | | NFS4ERR_MOVED, NFS4ERR_NOFILEHANDLE, | + | | NFS4ERR_OLD_STATEID, NFS4ERR_RESOURCE, | + | | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | + | | NFS4ERR_STALE_STATEID | + | | | + | COMMIT | NFS4ERR_ACCESS, NFS4ERR_BADHANDLE, | + | | NFS4ERR_BADXDR, NFS4ERR_DELAY, | + | | NFS4ERR_FHEXPIRED, NFS4ERR_INVAL, | + | | NFS4ERR_IO, NFS4ERR_ISDIR, NFS4ERR_MOVED, | + | | NFS4ERR_NOFILEHANDLE, NFS4ERR_RESOURCE, | + | | NFS4ERR_ROFS, NFS4ERR_SERVERFAULT, | + | | NFS4ERR_STALE, NFS4ERR_SYMLINK | + | | | + | CREATE | NFS4ERR_ACCESS, NFS4ERR_ATTRNOTSUPP, | + | | NFS4ERR_BADCHAR, NFS4ERR_BADHANDLE, | + | | NFS4ERR_BADNAME, NFS4ERR_BADOWNER, | + | | NFS4ERR_BADTYPE, NFS4ERR_BADXDR, | + | | NFS4ERR_DELAY, NFS4ERR_DQUOT, | + | | NFS4ERR_EXIST, NFS4ERR_FHEXPIRED, | + | | NFS4ERR_INVAL, NFS4ERR_IO, NFS4ERR_MOVED, | + | | NFS4ERR_NAMETOOLONG, NFS4ERR_NOFILEHANDLE, | + | | NFS4ERR_NOSPC, NFS4ERR_NOTDIR, | + | | NFS4ERR_PERM, NFS4ERR_RESOURCE, | + | | NFS4ERR_ROFS, NFS4ERR_SERVERFAULT, | + | | NFS4ERR_STALE | + + + +Haynes & Noveck Standards Track [Page 192] + +RFC 7530 NFSv4 March 2015 + + + | | | + | DELEGPURGE | NFS4ERR_BADXDR, NFS4ERR_DELAY, | + | | NFS4ERR_LEASE_MOVED, NFS4ERR_NOTSUPP, | + | | NFS4ERR_RESOURCE, NFS4ERR_SERVERFAULT, | + | | NFS4ERR_STALE_CLIENTID | + | | | + | DELEGRETURN | NFS4ERR_ADMIN_REVOKED, NFS4ERR_BAD_STATEID, | + | | NFS4ERR_BADXDR, NFS4ERR_DELAY, | + | | NFS4ERR_EXPIRED, NFS4ERR_INVAL, | + | | NFS4ERR_LEASE_MOVED, NFS4ERR_MOVED, | + | | NFS4ERR_NOFILEHANDLE, NFS4ERR_NOTSUPP, | + | | NFS4ERR_OLD_STATEID, NFS4ERR_RESOURCE, | + | | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | + | | NFS4ERR_STALE_STATEID | + | | | + | GETATTR | NFS4ERR_ACCESS, NFS4ERR_BADHANDLE, | + | | NFS4ERR_BADXDR, NFS4ERR_DELAY, | + | | NFS4ERR_FHEXPIRED, NFS4ERR_GRACE, | + | | NFS4ERR_INVAL, NFS4ERR_IO, NFS4ERR_MOVED, | + | | NFS4ERR_NOFILEHANDLE, NFS4ERR_RESOURCE, | + | | NFS4ERR_SERVERFAULT, NFS4ERR_STALE | + | | | + | GETFH | NFS4ERR_BADHANDLE, NFS4ERR_FHEXPIRED, | + | | NFS4ERR_MOVED, NFS4ERR_NOFILEHANDLE, | + | | NFS4ERR_RESOURCE, NFS4ERR_SERVERFAULT, | + | | NFS4ERR_STALE | + | | | + | ILLEGAL | NFS4ERR_BADXDR, NFS4ERR_OP_ILLEGAL | + | | | + | LINK | NFS4ERR_ACCESS, NFS4ERR_BADCHAR, | + | | NFS4ERR_BADHANDLE, NFS4ERR_BADNAME, | + | | NFS4ERR_BADXDR, NFS4ERR_DELAY, | + | | NFS4ERR_DQUOT, NFS4ERR_EXIST, | + | | NFS4ERR_FHEXPIRED, NFS4ERR_FILE_OPEN, | + | | NFS4ERR_INVAL, NFS4ERR_IO, NFS4ERR_ISDIR, | + | | NFS4ERR_MLINK, NFS4ERR_MOVED, | + | | NFS4ERR_NAMETOOLONG, NFS4ERR_NOENT, | + | | NFS4ERR_NOFILEHANDLE, NFS4ERR_NOSPC, | + | | NFS4ERR_NOTDIR, NFS4ERR_NOTSUPP, | + | | NFS4ERR_RESOURCE, NFS4ERR_ROFS, | + | | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | + | | NFS4ERR_WRONGSEC, NFS4ERR_XDEV | + | | | + + + + + + + + +Haynes & Noveck Standards Track [Page 193] + +RFC 7530 NFSv4 March 2015 + + + | LOCK | NFS4ERR_ACCESS, NFS4ERR_ADMIN_REVOKED, | + | | NFS4ERR_BADHANDLE, NFS4ERR_BAD_RANGE, | + | | NFS4ERR_BAD_SEQID, NFS4ERR_BAD_STATEID, | + | | NFS4ERR_BADXDR, NFS4ERR_DEADLOCK, | + | | NFS4ERR_DELAY, NFS4ERR_DENIED, | + | | NFS4ERR_EXPIRED, NFS4ERR_FHEXPIRED, | + | | NFS4ERR_GRACE, NFS4ERR_INVAL, | + | | NFS4ERR_ISDIR, NFS4ERR_LEASE_MOVED, | + | | NFS4ERR_LOCK_NOTSUPP, NFS4ERR_LOCK_RANGE, | + | | NFS4ERR_MOVED, NFS4ERR_NOFILEHANDLE, | + | | NFS4ERR_NO_GRACE, NFS4ERR_OLD_STATEID, | + | | NFS4ERR_OPENMODE, NFS4ERR_RECLAIM_BAD, | + | | NFS4ERR_RECLAIM_CONFLICT, NFS4ERR_RESOURCE, | + | | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | + | | NFS4ERR_STALE_CLIENTID, | + | | NFS4ERR_STALE_STATEID | + | | | + | LOCKT | NFS4ERR_ACCESS, NFS4ERR_BADHANDLE, | + | | NFS4ERR_BAD_RANGE, NFS4ERR_BADXDR, | + | | NFS4ERR_DELAY, NFS4ERR_DENIED, | + | | NFS4ERR_EXPIRED, NFS4ERR_FHEXPIRED, | + | | NFS4ERR_GRACE, NFS4ERR_INVAL, | + | | NFS4ERR_ISDIR, NFS4ERR_LEASE_MOVED, | + | | NFS4ERR_LOCK_RANGE, NFS4ERR_MOVED, | + | | NFS4ERR_NOFILEHANDLE, NFS4ERR_RESOURCE, | + | | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | + | | NFS4ERR_STALE_CLIENTID | + | | | + | LOCKU | NFS4ERR_ACCESS, NFS4ERR_ADMIN_REVOKED, | + | | NFS4ERR_BADHANDLE, NFS4ERR_BAD_RANGE, | + | | NFS4ERR_BAD_SEQID, NFS4ERR_BAD_STATEID, | + | | NFS4ERR_BADXDR, NFS4ERR_DELAY, | + | | NFS4ERR_EXPIRED, NFS4ERR_FHEXPIRED, | + | | NFS4ERR_GRACE, NFS4ERR_INVAL, | + | | NFS4ERR_ISDIR, NFS4ERR_LEASE_MOVED, | + | | NFS4ERR_LOCK_RANGE, NFS4ERR_MOVED, | + | | NFS4ERR_NOFILEHANDLE, NFS4ERR_OLD_STATEID, | + | | NFS4ERR_RESOURCE, NFS4ERR_SERVERFAULT, | + | | NFS4ERR_STALE, NFS4ERR_STALE_STATEID | + | | | + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 194] + +RFC 7530 NFSv4 March 2015 + + + | LOOKUP | NFS4ERR_ACCESS, NFS4ERR_BADCHAR, | + | | NFS4ERR_BADHANDLE, NFS4ERR_BADNAME, | + | | NFS4ERR_BADXDR, NFS4ERR_DELAY, | + | | NFS4ERR_FHEXPIRED, NFS4ERR_INVAL, | + | | NFS4ERR_IO, NFS4ERR_MOVED, | + | | NFS4ERR_NAMETOOLONG, NFS4ERR_NOENT, | + | | NFS4ERR_NOFILEHANDLE, NFS4ERR_NOTDIR, | + | | NFS4ERR_RESOURCE, NFS4ERR_SERVERFAULT, | + | | NFS4ERR_STALE, NFS4ERR_SYMLINK, | + | | NFS4ERR_WRONGSEC | + | | | + | LOOKUPP | NFS4ERR_ACCESS, NFS4ERR_BADHANDLE, | + | | NFS4ERR_DELAY, NFS4ERR_FHEXPIRED, | + | | NFS4ERR_IO, NFS4ERR_MOVED, NFS4ERR_NOENT, | + | | NFS4ERR_NOFILEHANDLE, NFS4ERR_NOTDIR, | + | | NFS4ERR_RESOURCE, NFS4ERR_SERVERFAULT, | + | | NFS4ERR_STALE, NFS4ERR_SYMLINK, | + | | NFS4ERR_WRONGSEC | + | | | + | NVERIFY | NFS4ERR_ACCESS, NFS4ERR_ATTRNOTSUPP, | + | | NFS4ERR_BADCHAR, NFS4ERR_BADHANDLE, | + | | NFS4ERR_BADXDR, NFS4ERR_DELAY, | + | | NFS4ERR_FHEXPIRED, NFS4ERR_GRACE, | + | | NFS4ERR_INVAL, NFS4ERR_IO, NFS4ERR_MOVED, | + | | NFS4ERR_NOFILEHANDLE, NFS4ERR_SAME, | + | | NFS4ERR_SERVERFAULT, NFS4ERR_STALE | + | | | + | OPEN | NFS4ERR_ACCESS, NFS4ERR_ADMIN_REVOKED, | + | | NFS4ERR_ATTRNOTSUPP, NFS4ERR_BADCHAR, | + | | NFS4ERR_BADHANDLE, NFS4ERR_BADNAME, | + | | NFS4ERR_BADOWNER, NFS4ERR_BAD_SEQID, | + | | NFS4ERR_BAD_STATEID, NFS4ERR_BADXDR, | + | | NFS4ERR_DELAY, NFS4ERR_DQUOT, | + | | NFS4ERR_EXIST, NFS4ERR_EXPIRED, | + | | NFS4ERR_FBIG, NFS4ERR_FHEXPIRED, | + | | NFS4ERR_GRACE, NFS4ERR_INVAL, NFS4ERR_IO, | + | | NFS4ERR_ISDIR, NFS4ERR_MOVED, | + | | NFS4ERR_NAMETOOLONG, NFS4ERR_NOENT, | + | | NFS4ERR_NOFILEHANDLE, NFS4ERR_NO_GRACE, | + | | NFS4ERR_NOSPC, NFS4ERR_NOTDIR, | + | | NFS4ERR_NOTSUPP, NFS4ERR_OLD_STATEID, | + | | NFS4ERR_PERM, NFS4ERR_RECLAIM_BAD, | + | | NFS4ERR_RECLAIM_CONFLICT, NFS4ERR_RESOURCE, | + | | NFS4ERR_ROFS, NFS4ERR_SERVERFAULT, | + | | NFS4ERR_SHARE_DENIED, NFS4ERR_STALE, | + | | NFS4ERR_STALE_CLIENTID, NFS4ERR_SYMLINK, | + | | NFS4ERR_WRONGSEC | + | | | + + + +Haynes & Noveck Standards Track [Page 195] + +RFC 7530 NFSv4 March 2015 + + + | OPENATTR | NFS4ERR_ACCESS, NFS4ERR_BADHANDLE, | + | | NFS4ERR_BADXDR, NFS4ERR_DELAY, | + | | NFS4ERR_DQUOT, NFS4ERR_FHEXPIRED, | + | | NFS4ERR_IO, NFS4ERR_MOVED, NFS4ERR_NOENT, | + | | NFS4ERR_NOFILEHANDLE, NFS4ERR_NOSPC, | + | | NFS4ERR_NOTSUPP, NFS4ERR_RESOURCE, | + | | NFS4ERR_ROFS, NFS4ERR_SERVERFAULT, | + | | NFS4ERR_STALE | + | | | + | OPEN_CONFIRM | NFS4ERR_ADMIN_REVOKED, NFS4ERR_BADHANDLE, | + | | NFS4ERR_BAD_SEQID, NFS4ERR_BAD_STATEID, | + | | NFS4ERR_BADXDR, NFS4ERR_EXPIRED, | + | | NFS4ERR_FHEXPIRED, NFS4ERR_INVAL, | + | | NFS4ERR_ISDIR, NFS4ERR_LEASE_MOVED, | + | | NFS4ERR_MOVED, NFS4ERR_NOFILEHANDLE, | + | | NFS4ERR_OLD_STATEID, NFS4ERR_RESOURCE, | + | | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | + | | NFS4ERR_STALE_STATEID | + | | | + | OPEN_DOWNGRADE | NFS4ERR_ADMIN_REVOKED, NFS4ERR_BADHANDLE, | + | | NFS4ERR_BAD_SEQID, NFS4ERR_BAD_STATEID, | + | | NFS4ERR_BADXDR, NFS4ERR_DELAY, | + | | NFS4ERR_EXPIRED, NFS4ERR_FHEXPIRED, | + | | NFS4ERR_INVAL, NFS4ERR_LEASE_MOVED, | + | | NFS4ERR_LOCKS_HELD, NFS4ERR_MOVED, | + | | NFS4ERR_NOFILEHANDLE, NFS4ERR_OLD_STATEID, | + | | NFS4ERR_RESOURCE, NFS4ERR_ROFS, | + | | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | + | | NFS4ERR_STALE_STATEID | + | | | + | PUTFH | NFS4ERR_BADHANDLE, NFS4ERR_BADXDR, | + | | NFS4ERR_DELAY, NFS4ERR_FHEXPIRED, | + | | NFS4ERR_MOVED, NFS4ERR_SERVERFAULT, | + | | NFS4ERR_STALE, NFS4ERR_WRONGSEC | + | | | + | PUTPUBFH | NFS4ERR_DELAY, NFS4ERR_SERVERFAULT, | + | | NFS4ERR_WRONGSEC | + | | | + | PUTROOTFH | NFS4ERR_DELAY, NFS4ERR_SERVERFAULT, | + | | NFS4ERR_WRONGSEC | + | | | + + + + + + + + + + +Haynes & Noveck Standards Track [Page 196] + +RFC 7530 NFSv4 March 2015 + + + | READ | NFS4ERR_ACCESS, NFS4ERR_ADMIN_REVOKED, | + | | NFS4ERR_BADHANDLE, NFS4ERR_BAD_STATEID, | + | | NFS4ERR_BADXDR, NFS4ERR_DELAY, | + | | NFS4ERR_EXPIRED, NFS4ERR_FHEXPIRED, | + | | NFS4ERR_GRACE, NFS4ERR_INVAL, NFS4ERR_IO, | + | | NFS4ERR_ISDIR, NFS4ERR_LEASE_MOVED, | + | | NFS4ERR_LOCKED, NFS4ERR_MOVED, | + | | NFS4ERR_NOFILEHANDLE, NFS4ERR_OLD_STATEID, | + | | NFS4ERR_OPENMODE, NFS4ERR_RESOURCE, | + | | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | + | | NFS4ERR_STALE_STATEID, NFS4ERR_SYMLINK | + | | | + | READDIR | NFS4ERR_ACCESS, NFS4ERR_BAD_COOKIE, | + | | NFS4ERR_BADHANDLE, NFS4ERR_BADXDR, | + | | NFS4ERR_DELAY, NFS4ERR_FHEXPIRED, | + | | NFS4ERR_INVAL, NFS4ERR_IO, NFS4ERR_MOVED, | + | | NFS4ERR_NOFILEHANDLE, NFS4ERR_NOTDIR, | + | | NFS4ERR_NOT_SAME, NFS4ERR_RESOURCE, | + | | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | + | | NFS4ERR_TOOSMALL | + | | | + | READLINK | NFS4ERR_ACCESS, NFS4ERR_BADHANDLE, | + | | NFS4ERR_DELAY, NFS4ERR_FHEXPIRED, | + | | NFS4ERR_INVAL, NFS4ERR_IO, NFS4ERR_ISDIR, | + | | NFS4ERR_MOVED, NFS4ERR_NOFILEHANDLE, | + | | NFS4ERR_NOTSUPP, NFS4ERR_RESOURCE, | + | | NFS4ERR_SERVERFAULT, NFS4ERR_STALE | + | | | + | RELEASE_LOCKOWNER | NFS4ERR_BADXDR, NFS4ERR_EXPIRED, | + | | NFS4ERR_LEASE_MOVED, NFS4ERR_LOCKS_HELD, | + | | NFS4ERR_RESOURCE, NFS4ERR_SERVERFAULT, | + | | NFS4ERR_STALE_CLIENTID | + | | | + | REMOVE | NFS4ERR_ACCESS, NFS4ERR_BADCHAR, | + | | NFS4ERR_BADHANDLE, NFS4ERR_BADNAME, | + | | NFS4ERR_BADXDR, NFS4ERR_DELAY, | + | | NFS4ERR_FHEXPIRED, NFS4ERR_FILE_OPEN, | + | | NFS4ERR_GRACE, NFS4ERR_INVAL, NFS4ERR_IO, | + | | NFS4ERR_MOVED, NFS4ERR_NAMETOOLONG, | + | | NFS4ERR_NOENT, NFS4ERR_NOFILEHANDLE, | + | | NFS4ERR_NOTDIR, NFS4ERR_NOTEMPTY, | + | | NFS4ERR_RESOURCE, NFS4ERR_ROFS, | + | | NFS4ERR_SERVERFAULT, NFS4ERR_STALE | + | | | + + + + + + + +Haynes & Noveck Standards Track [Page 197] + +RFC 7530 NFSv4 March 2015 + + + | RENAME | NFS4ERR_ACCESS, NFS4ERR_BADCHAR, | + | | NFS4ERR_BADHANDLE, NFS4ERR_BADNAME, | + | | NFS4ERR_BADXDR, NFS4ERR_DELAY, | + | | NFS4ERR_DQUOT, NFS4ERR_EXIST, | + | | NFS4ERR_FHEXPIRED, NFS4ERR_FILE_OPEN, | + | | NFS4ERR_GRACE, NFS4ERR_INVAL, NFS4ERR_IO, | + | | NFS4ERR_MOVED, NFS4ERR_NAMETOOLONG, | + | | NFS4ERR_NOENT, NFS4ERR_NOFILEHANDLE, | + | | NFS4ERR_NOSPC, NFS4ERR_NOTDIR, | + | | NFS4ERR_NOTEMPTY, NFS4ERR_RESOURCE, | + | | NFS4ERR_ROFS, NFS4ERR_SERVERFAULT, | + | | NFS4ERR_STALE, NFS4ERR_WRONGSEC, | + | | NFS4ERR_XDEV | + | | | + | RENEW | NFS4ERR_ACCESS, NFS4ERR_BADXDR, | + | | NFS4ERR_CB_PATH_DOWN, NFS4ERR_EXPIRED, | + | | NFS4ERR_LEASE_MOVED, NFS4ERR_RESOURCE, | + | | NFS4ERR_SERVERFAULT, NFS4ERR_STALE_CLIENTID | + | | | + | RESTOREFH | NFS4ERR_BADHANDLE, NFS4ERR_FHEXPIRED, | + | | NFS4ERR_MOVED, NFS4ERR_RESOURCE, | + | | NFS4ERR_RESTOREFH, NFS4ERR_SERVERFAULT, | + | | NFS4ERR_STALE, NFS4ERR_WRONGSEC | + | | | + | SAVEFH | NFS4ERR_BADHANDLE, NFS4ERR_FHEXPIRED, | + | | NFS4ERR_MOVED, NFS4ERR_NOFILEHANDLE, | + | | NFS4ERR_RESOURCE, NFS4ERR_SERVERFAULT, | + | | NFS4ERR_STALE | + | | | + | SECINFO | NFS4ERR_ACCESS, NFS4ERR_BADCHAR, | + | | NFS4ERR_BADHANDLE, NFS4ERR_BADNAME, | + | | NFS4ERR_BADXDR, NFS4ERR_DELAY, | + | | NFS4ERR_FHEXPIRED, NFS4ERR_INVAL, | + | | NFS4ERR_MOVED, NFS4ERR_NAMETOOLONG, | + | | NFS4ERR_NOENT, NFS4ERR_NOFILEHANDLE, | + | | NFS4ERR_NOTDIR, NFS4ERR_RESOURCE, | + | | NFS4ERR_SERVERFAULT, NFS4ERR_STALE | + | | | + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 198] + +RFC 7530 NFSv4 March 2015 + + + | SETATTR | NFS4ERR_ACCESS, NFS4ERR_ADMIN_REVOKED, | + | | NFS4ERR_ATTRNOTSUPP, NFS4ERR_BADCHAR, | + | | NFS4ERR_BADHANDLE, NFS4ERR_BADOWNER, | + | | NFS4ERR_BAD_STATEID, NFS4ERR_BADXDR, | + | | NFS4ERR_DELAY, NFS4ERR_DQUOT, | + | | NFS4ERR_EXPIRED, NFS4ERR_FBIG, | + | | NFS4ERR_FHEXPIRED, NFS4ERR_GRACE, | + | | NFS4ERR_INVAL, NFS4ERR_IO, NFS4ERR_ISDIR, | + | | NFS4ERR_LEASE_MOVED, NFS4ERR_LOCKED, | + | | NFS4ERR_MOVED, NFS4ERR_NOFILEHANDLE, | + | | NFS4ERR_NOSPC, NFS4ERR_OLD_STATEID, | + | | NFS4ERR_OPENMODE, NFS4ERR_PERM, | + | | NFS4ERR_RESOURCE, NFS4ERR_ROFS, | + | | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | + | | NFS4ERR_STALE_STATEID | + | | | + | SETCLIENTID | NFS4ERR_BADXDR, NFS4ERR_CLID_INUSE, | + | | NFS4ERR_DELAY, NFS4ERR_INVAL, | + | | NFS4ERR_RESOURCE, NFS4ERR_SERVERFAULT | + | | | + | SETCLIENTID_CONFIRM | NFS4ERR_BADXDR, NFS4ERR_CLID_INUSE, | + | | NFS4ERR_DELAY, NFS4ERR_RESOURCE, | + | | NFS4ERR_SERVERFAULT, NFS4ERR_STALE_CLIENTID | + | | | + | VERIFY | NFS4ERR_ACCESS, NFS4ERR_ATTRNOTSUPP, | + | | NFS4ERR_BADCHAR, NFS4ERR_BADHANDLE, | + | | NFS4ERR_BADXDR, NFS4ERR_DELAY, | + | | NFS4ERR_FHEXPIRED, NFS4ERR_GRACE, | + | | NFS4ERR_INVAL, NFS4ERR_IO, NFS4ERR_MOVED, | + | | NFS4ERR_NOFILEHANDLE, NFS4ERR_NOT_SAME, | + | | NFS4ERR_RESOURCE, NFS4ERR_SERVERFAULT, | + | | NFS4ERR_STALE | + | | | + + + + + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 199] + +RFC 7530 NFSv4 March 2015 + + + | WRITE | NFS4ERR_ACCESS, NFS4ERR_ADMIN_REVOKED, | + | | NFS4ERR_BADHANDLE, NFS4ERR_BAD_STATEID, | + | | NFS4ERR_BADXDR, NFS4ERR_DELAY, | + | | NFS4ERR_DQUOT, NFS4ERR_EXPIRED, | + | | NFS4ERR_FBIG, NFS4ERR_FHEXPIRED, | + | | NFS4ERR_GRACE, NFS4ERR_INVAL, NFS4ERR_IO, | + | | NFS4ERR_ISDIR, NFS4ERR_LEASE_MOVED, | + | | NFS4ERR_LOCKED, NFS4ERR_MOVED, | + | | NFS4ERR_NOFILEHANDLE, NFS4ERR_NOSPC, | + | | NFS4ERR_NXIO, NFS4ERR_OLD_STATEID, | + | | NFS4ERR_OPENMODE, NFS4ERR_RESOURCE, | + | | NFS4ERR_ROFS, NFS4ERR_SERVERFAULT, | + | | NFS4ERR_STALE, NFS4ERR_STALE_STATEID, | + | | NFS4ERR_SYMLINK | + | | | + +---------------------+---------------------------------------------+ + + Table 7: Valid Error Returns for Each Protocol Operation + +13.3. Callback Operations and Their Valid Errors + + This section contains a table that gives the valid error returns for + each callback operation. The error code NFS4_OK (indicating no + error) is not listed but should be understood to be returnable by all + callback operations, with the exception of CB_ILLEGAL. + + +-------------+-----------------------------------------------------+ + | Callback | Errors | + | Operation | | + +-------------+-----------------------------------------------------+ + | CB_GETATTR | NFS4ERR_BADHANDLE, NFS4ERR_BADXDR, NFS4ERR_DELAY, | + | | NFS4ERR_INVAL, NFS4ERR_SERVERFAULT | + | | | + | CB_ILLEGAL | NFS4ERR_BADXDR, NFS4ERR_OP_ILLEGAL | + | | | + | CB_RECALL | NFS4ERR_BADHANDLE, NFS4ERR_BAD_STATEID, | + | | NFS4ERR_BADXDR, NFS4ERR_DELAY, NFS4ERR_SERVERFAULT | + | | | + +-------------+-----------------------------------------------------+ + + Table 8: Valid Error Returns for Each Protocol Callback Operation + + + + + + + + + + +Haynes & Noveck Standards Track [Page 200] + +RFC 7530 NFSv4 March 2015 + + +13.4. Errors and the Operations That Use Them + + +--------------------------+----------------------------------------+ + | Error | Operations | + +--------------------------+----------------------------------------+ + | NFS4ERR_ACCESS | ACCESS, COMMIT, CREATE, GETATTR, LINK, | + | | LOCK, LOCKT, LOCKU, LOOKUP, LOOKUPP, | + | | NVERIFY, OPEN, OPENATTR, READ, | + | | READDIR, READLINK, REMOVE, RENAME, | + | | RENEW, SECINFO, SETATTR, VERIFY, WRITE | + | | | + | NFS4ERR_ADMIN_REVOKED | CLOSE, DELEGRETURN, LOCK, LOCKU, OPEN, | + | | OPEN_CONFIRM, OPEN_DOWNGRADE, READ, | + | | SETATTR, WRITE | + | | | + | NFS4ERR_ATTRNOTSUPP | CREATE, NVERIFY, OPEN, SETATTR, VERIFY | + | | | + | NFS4ERR_BADCHAR | CREATE, LINK, LOOKUP, NVERIFY, OPEN, | + | | REMOVE, RENAME, SECINFO, SETATTR, | + | | VERIFY | + | | | + | NFS4ERR_BADHANDLE | ACCESS, CB_GETATTR, CB_RECALL, CLOSE, | + | | COMMIT, CREATE, GETATTR, GETFH, LINK, | + | | LOCK, LOCKT, LOCKU, LOOKUP, LOOKUPP, | + | | NVERIFY, OPEN, OPENATTR, OPEN_CONFIRM, | + | | OPEN_DOWNGRADE, PUTFH, READ, READDIR, | + | | READLINK, REMOVE, RENAME, RESTOREFH, | + | | SAVEFH, SECINFO, SETATTR, VERIFY, | + | | WRITE | + | | | + | NFS4ERR_BADNAME | CREATE, LINK, LOOKUP, OPEN, REMOVE, | + | | RENAME, SECINFO | + | | | + | NFS4ERR_BADOWNER | CREATE, OPEN, SETATTR | + | | | + | NFS4ERR_BADTYPE | CREATE | + | | | + | NFS4ERR_BADXDR | ACCESS, CB_GETATTR, CB_ILLEGAL, | + | | CB_RECALL, CLOSE, COMMIT, CREATE, | + | | DELEGPURGE, DELEGRETURN, GETATTR, | + | | ILLEGAL, LINK, LOCK, LOCKT, LOCKU, | + | | LOOKUP, NVERIFY, OPEN, OPENATTR, | + | | OPEN_CONFIRM, OPEN_DOWNGRADE, PUTFH, | + | | READ, READDIR, RELEASE_LOCKOWNER, | + | | REMOVE, RENAME, RENEW, SECINFO, | + | | SETATTR, SETCLIENTID, | + | | SETCLIENTID_CONFIRM, VERIFY, WRITE | + | | | + + + +Haynes & Noveck Standards Track [Page 201] + +RFC 7530 NFSv4 March 2015 + + + | NFS4ERR_BAD_COOKIE | READDIR | + | | | + | NFS4ERR_BAD_RANGE | LOCK, LOCKT, LOCKU | + | | | + | NFS4ERR_BAD_SEQID | CLOSE, LOCK, LOCKU, OPEN, | + | | OPEN_CONFIRM, OPEN_DOWNGRADE | + | | | + | NFS4ERR_BAD_STATEID | CB_RECALL, CLOSE, DELEGRETURN, LOCK, | + | | LOCKU, OPEN, OPEN_CONFIRM, | + | | OPEN_DOWNGRADE, READ, SETATTR, WRITE | + | | | + | NFS4ERR_CB_PATH_DOWN | RENEW | + | | | + | NFS4ERR_CLID_INUSE | SETCLIENTID, SETCLIENTID_CONFIRM | + | | | + | NFS4ERR_DEADLOCK | LOCK | + | | | + | NFS4ERR_DELAY | ACCESS, CB_GETATTR, CB_RECALL, CLOSE, | + | | COMMIT, CREATE, DELEGPURGE, | + | | DELEGRETURN, GETATTR, LINK, LOCK, | + | | LOCKT, LOCKU, LOOKUP, LOOKUPP, | + | | NVERIFY, OPEN, OPENATTR, | + | | OPEN_DOWNGRADE, PUTFH, PUTPUBFH, | + | | PUTROOTFH, READ, READDIR, READLINK, | + | | REMOVE, RENAME, SECINFO, SETATTR, | + | | SETCLIENTID, SETCLIENTID_CONFIRM, | + | | VERIFY, WRITE | + | | | + | NFS4ERR_DENIED | LOCK, LOCKT | + | | | + | NFS4ERR_DQUOT | CREATE, LINK, OPEN, OPENATTR, RENAME, | + | | SETATTR, WRITE | + | | | + | NFS4ERR_EXIST | CREATE, LINK, OPEN, RENAME | + | | | + | NFS4ERR_EXPIRED | CLOSE, DELEGRETURN, LOCK, LOCKT, | + | | LOCKU, OPEN, OPEN_CONFIRM, | + | | OPEN_DOWNGRADE, READ, | + | | RELEASE_LOCKOWNER, RENEW, SETATTR, | + | | WRITE | + | | | + | NFS4ERR_FBIG | OPEN, SETATTR, WRITE | + | | | + + + + + + + + +Haynes & Noveck Standards Track [Page 202] + +RFC 7530 NFSv4 March 2015 + + + | NFS4ERR_FHEXPIRED | ACCESS, CLOSE, COMMIT, CREATE, | + | | GETATTR, GETFH, LINK, LOCK, LOCKT, | + | | LOCKU, LOOKUP, LOOKUPP, NVERIFY, OPEN, | + | | OPENATTR, OPEN_CONFIRM, | + | | OPEN_DOWNGRADE, PUTFH, READ, READDIR, | + | | READLINK, REMOVE, RENAME, RESTOREFH, | + | | SAVEFH, SECINFO, SETATTR, VERIFY, | + | | WRITE | + | | | + | NFS4ERR_FILE_OPEN | LINK, REMOVE, RENAME | + | | | + | NFS4ERR_GRACE | GETATTR, LOCK, LOCKT, LOCKU, NVERIFY, | + | | OPEN, READ, REMOVE, RENAME, SETATTR, | + | | VERIFY, WRITE | + | | | + | NFS4ERR_INVAL | ACCESS, CB_GETATTR, CLOSE, COMMIT, | + | | CREATE, DELEGRETURN, GETATTR, LINK, | + | | LOCK, LOCKT, LOCKU, LOOKUP, NVERIFY, | + | | OPEN, OPEN_CONFIRM, OPEN_DOWNGRADE, | + | | READ, READDIR, READLINK, REMOVE, | + | | RENAME, SECINFO, SETATTR, SETCLIENTID, | + | | VERIFY, WRITE | + | | | + | NFS4ERR_IO | ACCESS, COMMIT, CREATE, GETATTR, LINK, | + | | LOOKUP, LOOKUPP, NVERIFY, OPEN, | + | | OPENATTR, READ, READDIR, READLINK, | + | | REMOVE, RENAME, SETATTR, VERIFY, WRITE | + | | | + | NFS4ERR_ISDIR | CLOSE, COMMIT, LINK, LOCK, LOCKT, | + | | LOCKU, OPEN, OPEN_CONFIRM, READ, | + | | READLINK, SETATTR, WRITE | + | | | + | NFS4ERR_LEASE_MOVED | CLOSE, DELEGPURGE, DELEGRETURN, LOCK, | + | | LOCKT, LOCKU, OPEN_CONFIRM, | + | | OPEN_DOWNGRADE, READ, | + | | RELEASE_LOCKOWNER, RENEW, SETATTR, | + | | WRITE | + | | | + | NFS4ERR_LOCKED | READ, SETATTR, WRITE | + | | | + | NFS4ERR_LOCKS_HELD | CLOSE, OPEN_DOWNGRADE, | + | | RELEASE_LOCKOWNER | + | | | + | NFS4ERR_LOCK_NOTSUPP | LOCK | + | | | + | NFS4ERR_LOCK_RANGE | LOCK, LOCKT, LOCKU | + | | | + | NFS4ERR_MLINK | LINK | + + + +Haynes & Noveck Standards Track [Page 203] + +RFC 7530 NFSv4 March 2015 + + + | | | + | NFS4ERR_MOVED | ACCESS, CLOSE, COMMIT, CREATE, | + | | DELEGRETURN, GETATTR, GETFH, LINK, | + | | LOCK, LOCKT, LOCKU, LOOKUP, LOOKUPP, | + | | NVERIFY, OPEN, OPENATTR, OPEN_CONFIRM, | + | | OPEN_DOWNGRADE, PUTFH, READ, READDIR, | + | | READLINK, REMOVE, RENAME, RESTOREFH, | + | | SAVEFH, SECINFO, SETATTR, VERIFY, | + | | WRITE | + | | | + | NFS4ERR_NAMETOOLONG | CREATE, LINK, LOOKUP, OPEN, REMOVE, | + | | RENAME, SECINFO | + | | | + | NFS4ERR_NOENT | LINK, LOOKUP, LOOKUPP, OPEN, OPENATTR, | + | | REMOVE, RENAME, SECINFO | + | | | + | NFS4ERR_NOFILEHANDLE | ACCESS, CLOSE, COMMIT, CREATE, | + | | DELEGRETURN, GETATTR, GETFH, LINK, | + | | LOCK, LOCKT, LOCKU, LOOKUP, LOOKUPP, | + | | NVERIFY, OPEN, OPENATTR, OPEN_CONFIRM, | + | | OPEN_DOWNGRADE, READ, READDIR, | + | | READLINK, REMOVE, RENAME, SAVEFH, | + | | SECINFO, SETATTR, VERIFY, WRITE | + | | | + | NFS4ERR_NOSPC | CREATE, LINK, OPEN, OPENATTR, RENAME, | + | | SETATTR, WRITE | + | | | + | NFS4ERR_NOTDIR | CREATE, LINK, LOOKUP, LOOKUPP, OPEN, | + | | READDIR, REMOVE, RENAME, SECINFO | + | | | + | NFS4ERR_NOTEMPTY | REMOVE, RENAME | + | | | + | NFS4ERR_NOTSUPP | DELEGPURGE, DELEGRETURN, LINK, OPEN, | + | | OPENATTR, READLINK | + | | | + | NFS4ERR_NOT_SAME | READDIR, VERIFY | + | | | + | NFS4ERR_NO_GRACE | LOCK, OPEN | + | | | + | NFS4ERR_NXIO | WRITE | + | | | + | NFS4ERR_OLD_STATEID | CLOSE, DELEGRETURN, LOCK, LOCKU, OPEN, | + | | OPEN_CONFIRM, OPEN_DOWNGRADE, READ, | + | | SETATTR, WRITE | + | | | + | NFS4ERR_OPENMODE | LOCK, READ, SETATTR, WRITE | + | | | + | NFS4ERR_OP_ILLEGAL | CB_ILLEGAL, ILLEGAL | + + + +Haynes & Noveck Standards Track [Page 204] + +RFC 7530 NFSv4 March 2015 + + + | | | + | NFS4ERR_PERM | CREATE, OPEN, SETATTR | + | | | + | NFS4ERR_RECLAIM_BAD | LOCK, OPEN | + | | | + | NFS4ERR_RECLAIM_CONFLICT | LOCK, OPEN | + | | | + | NFS4ERR_RESOURCE | ACCESS, CLOSE, COMMIT, CREATE, | + | | DELEGPURGE, DELEGRETURN, GETATTR, | + | | GETFH, LINK, LOCK, LOCKT, LOCKU, | + | | LOOKUP, LOOKUPP, OPEN, OPENATTR, | + | | OPEN_CONFIRM, OPEN_DOWNGRADE, READ, | + | | READDIR, READLINK, RELEASE_LOCKOWNER, | + | | REMOVE, RENAME, RENEW, RESTOREFH, | + | | SAVEFH, SECINFO, SETATTR, SETCLIENTID, | + | | SETCLIENTID_CONFIRM, VERIFY, WRITE | + | | | + | NFS4ERR_RESTOREFH | RESTOREFH | + | | | + | NFS4ERR_ROFS | COMMIT, CREATE, LINK, OPEN, OPENATTR, | + | | OPEN_DOWNGRADE, REMOVE, RENAME, | + | | SETATTR, WRITE | + | | | + | NFS4ERR_SAME | NVERIFY | + | | | + | NFS4ERR_SERVERFAULT | ACCESS, CB_GETATTR, CB_RECALL, CLOSE, | + | | COMMIT, CREATE, DELEGPURGE, | + | | DELEGRETURN, GETATTR, GETFH, LINK, | + | | LOCK, LOCKT, LOCKU, LOOKUP, LOOKUPP, | + | | NVERIFY, OPEN, OPENATTR, OPEN_CONFIRM, | + | | OPEN_DOWNGRADE, PUTFH, PUTPUBFH, | + | | PUTROOTFH, READ, READDIR, READLINK, | + | | RELEASE_LOCKOWNER, REMOVE, RENAME, | + | | RENEW, RESTOREFH, SAVEFH, SECINFO, | + | | SETATTR, SETCLIENTID, | + | | SETCLIENTID_CONFIRM, VERIFY, WRITE | + | | | + | NFS4ERR_SHARE_DENIED | OPEN | + | | | + | NFS4ERR_STALE | ACCESS, CLOSE, COMMIT, CREATE, | + | | DELEGRETURN, GETATTR, GETFH, LINK, | + | | LOCK, LOCKT, LOCKU, LOOKUP, LOOKUPP, | + | | NVERIFY, OPEN, OPENATTR, OPEN_CONFIRM, | + | | OPEN_DOWNGRADE, PUTFH, READ, READDIR, | + | | READLINK, REMOVE, RENAME, RESTOREFH, | + | | SAVEFH, SECINFO, SETATTR, VERIFY, | + | | WRITE | + | | | + + + +Haynes & Noveck Standards Track [Page 205] + +RFC 7530 NFSv4 March 2015 + + + | NFS4ERR_STALE_CLIENTID | DELEGPURGE, LOCK, LOCKT, OPEN, | + | | RELEASE_LOCKOWNER, RENEW, | + | | SETCLIENTID_CONFIRM | + | | | + | NFS4ERR_STALE_STATEID | CLOSE, DELEGRETURN, LOCK, LOCKU, | + | | OPEN_CONFIRM, OPEN_DOWNGRADE, READ, | + | | SETATTR, WRITE | + | | | + | NFS4ERR_SYMLINK | COMMIT, LOOKUP, LOOKUPP, OPEN, READ, | + | | WRITE | + | | | + | NFS4ERR_TOOSMALL | READDIR | + | | | + | NFS4ERR_WRONGSEC | LINK, LOOKUP, LOOKUPP, OPEN, PUTFH, | + | | PUTPUBFH, PUTROOTFH, RENAME, RESTOREFH | + | | | + | NFS4ERR_XDEV | LINK, RENAME | + | | | + +--------------------------+----------------------------------------+ + + Table 9: Errors and the Operations That Use Them + +14. NFSv4 Requests + + For the NFSv4 RPC program, there are two traditional RPC procedures: + NULL and COMPOUND. All other functionality is defined as a set of + operations, and these operations are defined in normal XDR/RPC syntax + and semantics. However, these operations are encapsulated within the + COMPOUND procedure. This requires that the client combine one or + more of the NFSv4 operations into a single request. + + The NFS4_CALLBACK program is used to provide server-to-client + signaling and is constructed in a fashion similar to the NFSv4 + program. The procedures CB_NULL and CB_COMPOUND are defined in the + same way as NULL and COMPOUND are within the NFS program. The + CB_COMPOUND request also encapsulates the remaining operations of the + NFS4_CALLBACK program. There is no predefined RPC program number for + the NFS4_CALLBACK program. It is up to the client to specify a + program number in the "transient" program range. The program and + port numbers of the NFS4_CALLBACK program are provided by the client + as part of the SETCLIENTID/SETCLIENTID_CONFIRM sequence. The program + and port can be changed by another SETCLIENTID/SETCLIENTID_CONFIRM + sequence, and it is possible to use the sequence to change them + within a client incarnation without removing relevant leased client + state. + + + + + + +Haynes & Noveck Standards Track [Page 206] + +RFC 7530 NFSv4 March 2015 + + +14.1. COMPOUND Procedure + + The COMPOUND procedure provides the opportunity for better + performance within high-latency networks. The client can avoid + cumulative latency of multiple RPCs by combining multiple dependent + operations into a single COMPOUND procedure. A COMPOUND operation + may provide for protocol simplification by allowing the client to + combine basic procedures into a single request that is customized for + the client's environment. + + The CB_COMPOUND procedure precisely parallels the features of + COMPOUND as described above. + + The basic structure of the COMPOUND procedure is: + + +-----+--------------+--------+-----------+-----------+-----------+-- + | tag | minorversion | numops | op + args | op + args | op + args | + +-----+--------------+--------+-----------+-----------+-----------+-- + + and the reply's structure is: + + +------------+-----+--------+-----------------------+-- + |last status | tag | numres | status + op + results | + +------------+-----+--------+-----------------------+-- + + The numops and numres fields, used in the depiction above, represent + the count for the counted array encoding used to signify the number + of arguments or results encoded in the request and response. As per + the XDR encoding, these counts must match exactly the number of + operation arguments or results encoded. + +14.2. Evaluation of a COMPOUND Request + + The server will process the COMPOUND procedure by evaluating each of + the operations within the COMPOUND procedure in order. Each + component operation consists of a 32-bit operation code, followed by + the argument of length determined by the type of operation. The + results of each operation are encoded in sequence into a reply + buffer. The results of each operation are preceded by the opcode and + a status code (normally zero). If an operation results in a non-zero + status code, the status will be encoded, evaluation of the COMPOUND + sequence will halt, and the reply will be returned. Note that + evaluation stops even in the event of "non-error" conditions such as + NFS4ERR_SAME. + + + + + + + +Haynes & Noveck Standards Track [Page 207] + +RFC 7530 NFSv4 March 2015 + + + There are no atomicity requirements for the operations contained + within the COMPOUND procedure. The operations being evaluated as + part of a COMPOUND request may be evaluated simultaneously with other + COMPOUND requests that the server receives. + + A COMPOUND is not a transaction, and it is the client's + responsibility to recover from any partially completed COMPOUND + procedure. These may occur at any point due to errors such as + NFS4ERR_RESOURCE and NFS4ERR_DELAY. Note that these errors can occur + in an otherwise valid operation string. Further, a server reboot + that occurs in the middle of processing a COMPOUND procedure may + leave the client with the difficult task of determining how far + COMPOUND processing has proceeded. Therefore, the client should + avoid overly complex COMPOUND procedures in the event of the failure + of an operation within the procedure. + + Each operation assumes a current filehandle and a saved filehandle + that are available as part of the execution context of the COMPOUND + request. Operations may set, change, or return the current + filehandle. The saved filehandle is used for temporary storage of a + filehandle value and as operands for the RENAME and LINK operations. + +14.3. Synchronous Modifying Operations + + NFSv4 operations that modify the file system are synchronous. When + an operation is successfully completed at the server, the client can + trust that any data associated with the request is now in stable + storage (the one exception is in the case of the file data in a WRITE + operation with the UNSTABLE4 option specified). + + This implies that any previous operations within the same COMPOUND + request are also reflected in stable storage. This behavior enables + the client's ability to recover from a partially executed COMPOUND + request that may have resulted from the failure of the server. For + example, if a COMPOUND request contains operations A and B and the + server is unable to send a response to the client, then depending on + the progress the server made in servicing the request, the result of + both operations may be reflected in stable storage or just + operation A may be reflected. The server must not have just the + results of operation B in stable storage. + +14.4. Operation Values + + The operations encoded in the COMPOUND procedure are identified by + operation values. To avoid overlap with the RPC procedure numbers, + operations 0 (zero) and 1 are not defined. Operation 2 is not + defined but is reserved for future use with minor versioning. + + + + +Haynes & Noveck Standards Track [Page 208] + +RFC 7530 NFSv4 March 2015 + + +15. NFSv4 Procedures + +15.1. Procedure 0: NULL - No Operation + +15.1.1. SYNOPSIS + + + +15.1.2. ARGUMENT + + void; + +15.1.3. RESULT + + void; + +15.1.4. DESCRIPTION + + Standard NULL procedure. Void argument, void response. This + procedure has no functionality associated with it. Because of this, + it is sometimes used to measure the overhead of processing a service + request. Therefore, the server should ensure that no unnecessary + work is done in servicing this procedure. + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 209] + +RFC 7530 NFSv4 March 2015 + + +15.2. Procedure 1: COMPOUND - COMPOUND Operations + +15.2.1. SYNOPSIS + + compoundargs -> compoundres + +15.2.2. ARGUMENT + + union nfs_argop4 switch (nfs_opnum4 argop) { + case : ; + ... + }; + + struct COMPOUND4args { + utf8str_cs tag; + uint32_t minorversion; + nfs_argop4 argarray<>; + }; + +15.2.3. RESULT + + union nfs_resop4 switch (nfs_opnum4 resop) { + case : ; + ... + }; + + struct COMPOUND4res { + nfsstat4 status; + utf8str_cs tag; + nfs_resop4 resarray<>; + }; + +15.2.4. DESCRIPTION + + The COMPOUND procedure is used to combine one or more of the NFS + operations into a single RPC request. The main NFS RPC program has + two main procedures: NULL and COMPOUND. All other operations use the + COMPOUND procedure as a wrapper. + + The COMPOUND procedure is used to combine individual operations into + a single RPC request. The server interprets each of the operations + in turn. If an operation is executed by the server and the status of + that operation is NFS4_OK, then the next operation in the COMPOUND + procedure is executed. The server continues this process until there + are no more operations to be executed or one of the operations has a + status value other than NFS4_OK. + + + + + +Haynes & Noveck Standards Track [Page 210] + +RFC 7530 NFSv4 March 2015 + + + In the processing of the COMPOUND procedure, the server may find that + it does not have the available resources to execute any or all of the + operations within the COMPOUND sequence. In this case, the error + NFS4ERR_RESOURCE will be returned for the particular operation within + the COMPOUND procedure where the resource exhaustion occurred. This + assumes that all previous operations within the COMPOUND sequence + have been evaluated successfully. The results for all of the + evaluated operations must be returned to the client. + + The server will generally choose between two methods of decoding the + client's request. The first would be the traditional one-pass XDR + decode, in which decoding of the entire COMPOUND precedes execution + of any operation within it. If there is an XDR decoding error in + this case, an RPC XDR decode error would be returned. The second + method would be to make an initial pass to decode the basic COMPOUND + request and then to XDR decode each of the individual operations, as + the server is ready to execute it. In this case, the server may + encounter an XDR decode error during such an operation decode, after + previous operations within the COMPOUND have been executed. In this + case, the server would return the error NFS4ERR_BADXDR to signify the + decode error. + + The COMPOUND arguments contain a minorversion field. The initial and + default value for this field is 0 (zero). This field will be used by + future minor versions such that the client can communicate to the + server what minor version is being requested. If the server receives + a COMPOUND procedure with a minorversion field value that it does not + support, the server MUST return an error of + NFS4ERR_MINOR_VERS_MISMATCH and a zero-length resultdata array. + + Contained within the COMPOUND results is a status field. If the + results array length is non-zero, this status must be equivalent to + the status of the last operation that was executed within the + COMPOUND procedure. Therefore, if an operation incurred an error, + then the status value will be the same error value as is being + returned for the operation that failed. + + Note that operations 0 (zero), 1 (one), and 2 (two) are not defined + for the COMPOUND procedure. It is possible that the server receives + a request that contains an operation that is less than the first + legal operation (OP_ACCESS) or greater than the last legal operation + (OP_RELEASE_LOCKOWNER). In this case, the server's response will + encode the opcode OP_ILLEGAL rather than the illegal opcode of the + request. The status field in the ILLEGAL return results will be set + to NFS4ERR_OP_ILLEGAL. The COMPOUND procedure's return results will + also be NFS4ERR_OP_ILLEGAL. + + + + + +Haynes & Noveck Standards Track [Page 211] + +RFC 7530 NFSv4 March 2015 + + + The definition of the "tag" in the request is left to the + implementer. It may be used to summarize the content of the COMPOUND + request for the benefit of packet sniffers and engineers debugging + implementations. However, the value of "tag" in the response SHOULD + be the same value as the value provided in the request. This applies + to the tag field of the CB_COMPOUND procedure as well. + +15.2.4.1. Current Filehandle + + The current filehandle and the saved filehandle are used throughout + the protocol. Most operations implicitly use the current filehandle + as an argument, and many set the current filehandle as part of the + results. The combination of client-specified sequences of operations + and current and saved filehandle arguments and results allows for + greater protocol flexibility. The best or easiest example of current + filehandle usage is a sequence like the following: + + PUTFH fh1 {fh1} + LOOKUP "compA" {fh2} + GETATTR {fh2} + LOOKUP "compB" {fh3} + GETATTR {fh3} + LOOKUP "compC" {fh4} + GETATTR {fh4} + GETFH + + Figure 1: Filehandle Usage Example + + In this example, the PUTFH (Section 16.20) operation explicitly sets + the current filehandle value, while the result of each LOOKUP + operation sets the current filehandle value to the resultant file + system object. Also, the client is able to insert GETATTR operations + using the current filehandle as an argument. + + The PUTROOTFH (Section 16.22) and PUTPUBFH (Section 16.21) operations + also set the current filehandle. The above example would replace + "PUTFH fh1" with PUTROOTFH or PUTPUBFH with no filehandle argument in + order to achieve the same effect (on the assumption that "compA" is + directly below the root of the namespace). + + Along with the current filehandle, there is a saved filehandle. + While the current filehandle is set as the result of operations like + LOOKUP, the saved filehandle must be set directly with the use of the + SAVEFH operation. The SAVEFH operation copies the current filehandle + value to the saved value. The saved filehandle value is used in + combination with the current filehandle value for the LINK and RENAME + operations. The RESTOREFH operation will copy the saved filehandle + + + + +Haynes & Noveck Standards Track [Page 212] + +RFC 7530 NFSv4 March 2015 + + + value to the current filehandle value; as a result, the saved + filehandle value may be used as a sort of "scratch" area for the + client's series of operations. + +15.2.5. IMPLEMENTATION + + Since an error of any type may occur after only a portion of the + operations have been evaluated, the client must be prepared to + recover from any failure. If the source of an NFS4ERR_RESOURCE error + was a complex or lengthy set of operations, it is likely that if the + number of operations were reduced the server would be able to + evaluate them successfully. Therefore, the client is responsible for + dealing with this type of complexity in recovery. + + A single compound should not contain multiple operations that have + different values for the clientid field used in OPEN, LOCK, or RENEW. + This can cause confusion in cases in which operations that do not + contain clientids have potential interactions with operations that + do. When only a single clientid has been used, it is clear what + client is being referenced. For a particular example involving the + interaction of OPEN and GETATTR, see Section 16.16.6. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 213] + +RFC 7530 NFSv4 March 2015 + + +16. NFSv4 Operations + +16.1. Operation 3: ACCESS - Check Access Rights + +16.1.1. SYNOPSIS + + (cfh), accessreq -> supported, accessrights + +16.1.2. ARGUMENT + + const ACCESS4_READ = 0x00000001; + const ACCESS4_LOOKUP = 0x00000002; + const ACCESS4_MODIFY = 0x00000004; + const ACCESS4_EXTEND = 0x00000008; + const ACCESS4_DELETE = 0x00000010; + const ACCESS4_EXECUTE = 0x00000020; + + struct ACCESS4args { + /* CURRENT_FH: object */ + uint32_t access; + }; + +16.1.3. RESULT + + struct ACCESS4resok { + uint32_t supported; + uint32_t access; + }; + + union ACCESS4res switch (nfsstat4 status) { + case NFS4_OK: + ACCESS4resok resok4; + default: + void; + }; + +16.1.4. DESCRIPTION + + ACCESS determines the access rights that a user, as identified by the + credentials in the RPC request, has with respect to the file system + object specified by the current filehandle. The client encodes the + set of access rights that are to be checked in the bitmask "access". + The server checks the permissions encoded in the bitmask. If a + status of NFS4_OK is returned, two bitmasks are included in the + response. The first, "supported", represents the access rights for + which the server can verify reliably. The second, "access", + represents the access rights available to the user for the filehandle + provided. On success, the current filehandle retains its value. + + + +Haynes & Noveck Standards Track [Page 214] + +RFC 7530 NFSv4 March 2015 + + + Note that the supported field will contain only as many values as + were originally sent in the arguments. For example, if the client + sends an ACCESS operation with only the ACCESS4_READ value set and + the server supports this value, the server will return only + ACCESS4_READ even if it could have reliably checked other values. + + The results of this operation are necessarily advisory in nature. A + return status of NFS4_OK and the appropriate bit set in the bitmask + do not imply that such access will be allowed to the file system + object in the future. This is because access rights can be revoked + by the server at any time. + + The following access permissions may be requested: + + ACCESS4_READ: Read data from file or read a directory. + + ACCESS4_LOOKUP: Look up a name in a directory (no meaning for + non-directory objects). + + ACCESS4_MODIFY: Rewrite existing file data or modify existing + directory entries. + + ACCESS4_EXTEND: Write new data or add directory entries. + + ACCESS4_DELETE: Delete an existing directory entry. + + ACCESS4_EXECUTE: Execute file (no meaning for a directory). + + On success, the current filehandle retains its value. + +16.1.5. IMPLEMENTATION + + In general, it is not sufficient for the client to attempt to deduce + access permissions by inspecting the uid, gid, and mode fields in the + file attributes or by attempting to interpret the contents of the ACL + attribute. This is because the server may perform uid or gid mapping + or enforce additional access control restrictions. It is also + possible that the server may not be in the same ID space as the + client. In these cases (and perhaps others), the client cannot + reliably perform an access check with only current file attributes. + + In the NFSv2 protocol, the only reliable way to determine whether an + operation was allowed was to try it and see if it succeeded or + failed. Using the ACCESS operation in the NFSv4 protocol, the client + can ask the server to indicate whether or not one or more classes of + operations are permitted. The ACCESS operation is provided to allow + clients to check before doing a series of operations that might + result in an access failure. The OPEN operation provides a point + + + +Haynes & Noveck Standards Track [Page 215] + +RFC 7530 NFSv4 March 2015 + + + where the server can verify access to the file object and the method + to return that information to the client. The ACCESS operation is + still useful for directory operations or for use in the case where + the UNIX API "access" is used on the client. + + The information returned by the server in response to an ACCESS call + is not permanent. It was correct at the exact time that the server + performed the checks, but not necessarily afterward. The server can + revoke access permission at any time. + + The client should use the effective credentials of the user to build + the authentication information in the ACCESS request used to + determine access rights. It is the effective user and group + credentials that are used in subsequent READ and WRITE operations. + + Many implementations do not directly support the ACCESS4_DELETE + permission. Operating systems like UNIX will ignore the + ACCESS4_DELETE bit if set on an access request on a non-directory + object. In these systems, delete permission on a file is determined + by the access permissions on the directory in which the file resides, + instead of being determined by the permissions of the file itself. + Therefore, the mask returned enumerating which access rights can be + supported will have the ACCESS4_DELETE value set to 0. This + indicates to the client that the server was unable to check that + particular access right. The ACCESS4_DELETE bit in the access mask + returned will then be ignored by the client. + + + + + + + + + + + + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 216] + +RFC 7530 NFSv4 March 2015 + + +16.2. Operation 4: CLOSE - Close File + +16.2.1. SYNOPSIS + + (cfh), seqid, open_stateid -> open_stateid + +16.2.2. ARGUMENT + + struct CLOSE4args { + /* CURRENT_FH: object */ + seqid4 seqid; + stateid4 open_stateid; + }; + +16.2.3. RESULT + + union CLOSE4res switch (nfsstat4 status) { + case NFS4_OK: + stateid4 open_stateid; + default: + void; + }; + +16.2.4. DESCRIPTION + + The CLOSE operation releases share reservations for the regular or + named attribute file as specified by the current filehandle. The + share reservations and other state information released at the server + as a result of this CLOSE are only associated with the supplied + stateid. The sequence id provides for the correct ordering. State + associated with other OPENs is not affected. + + If byte-range locks are held, the client SHOULD release all locks + before issuing a CLOSE. The server MAY free all outstanding locks on + 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 locks would exist after the CLOSE. + + On success, the current filehandle retains its value. + +16.2.5. IMPLEMENTATION + + Even though CLOSE returns a stateid, this stateid is not useful to + the client and should be treated as deprecated. CLOSE "shuts down" + the state associated with all OPENs for the file by a single + open-owner. As noted above, CLOSE will either release all file + locking state or return an error. Therefore, the stateid returned by + CLOSE is not useful for the operations that follow. + + + +Haynes & Noveck Standards Track [Page 217] + +RFC 7530 NFSv4 March 2015 + + +16.3. Operation 5: COMMIT - Commit Cached Data + +16.3.1. SYNOPSIS + + (cfh), offset, count -> verifier + +16.3.2. ARGUMENT + + struct COMMIT4args { + /* CURRENT_FH: file */ + offset4 offset; + count4 count; + }; + +16.3.3. RESULT + + struct COMMIT4resok { + verifier4 writeverf; + }; + + union COMMIT4res switch (nfsstat4 status) { + case NFS4_OK: + COMMIT4resok resok4; + default: + void; + }; + +16.3.4. DESCRIPTION + + The COMMIT operation forces or flushes data to stable storage for the + file specified by the current filehandle. The flushed data is that + which was previously written with a WRITE operation that had the + stable field set to UNSTABLE4. + + The offset specifies the position within the file where the flush is + to begin. An offset value of 0 (zero) means to flush data starting + at the beginning of the file. The count specifies the number of + bytes of data to flush. If count is 0 (zero), a flush from the + offset to the end of the file is done. + + The server returns a write verifier upon successful completion of the + COMMIT. The write verifier is used by the client to determine if the + server has restarted or rebooted between the initial WRITE(s) and the + COMMIT. The client does this by comparing the write verifier + returned from the initial writes and the verifier returned by the + COMMIT operation. The server must vary the value of the write + verifier at each server event or instantiation that may lead to a + + + + +Haynes & Noveck Standards Track [Page 218] + +RFC 7530 NFSv4 March 2015 + + + loss of uncommitted data. Most commonly, this occurs when the server + is rebooted; however, other events at the server may result in + uncommitted data loss as well. + + On success, the current filehandle retains its value. + +16.3.5. IMPLEMENTATION + + The COMMIT operation is similar in operation and semantics to the + POSIX fsync() [fsync] system call that synchronizes a file's state + with the disk (file data and metadata are flushed to disk or stable + storage). COMMIT performs the same operation for a client, flushing + any unsynchronized data and metadata on the server to the server's + disk or stable storage for the specified file. Like fsync(), it may + be that there is some modified data or no modified data to + synchronize. The data may have been synchronized by the server's + normal periodic buffer synchronization activity. COMMIT should + return NFS4_OK, unless there has been an unexpected error. + + COMMIT differs from fsync() in that it is possible for the client to + flush a range of the file (most likely triggered by a buffer- + reclamation scheme on the client before the file has been completely + written). + + The server implementation of COMMIT is reasonably simple. If the + server receives a full file COMMIT request that is starting at offset + 0 and count 0, it should do the equivalent of fsync()'ing the file. + Otherwise, it should arrange to have the cached data in the range + specified by offset and count to be flushed to stable storage. In + both cases, any metadata associated with the file must be flushed to + stable storage before returning. It is not an error for there to be + nothing to flush on the server. This means that the data and + metadata that needed to be flushed have already been flushed or lost + during the last server failure. + + The client implementation of COMMIT is a little more complex. There + are two reasons for wanting to commit a client buffer to stable + storage. The first is that the client wants to reuse a buffer. In + this case, the offset and count of the buffer are sent to the server + in the COMMIT request. The server then flushes any cached data based + on the offset and count, and flushes any metadata associated with the + file. It then returns the status of the flush and the write + verifier. The other reason for the client to generate a COMMIT is + for a full file flush, such as may be done at CLOSE. In this case, + the client would gather all of the buffers for this file that contain + uncommitted data, do the COMMIT operation with an offset of 0 and + count of 0, and then free all of those buffers. Any other dirty + buffers would be sent to the server in the normal fashion. + + + +Haynes & Noveck Standards Track [Page 219] + +RFC 7530 NFSv4 March 2015 + + + After a buffer is written by the client with the stable parameter set + to UNSTABLE4, the buffer must be considered modified by the client + until the buffer has been either flushed via a COMMIT operation or + written via a WRITE operation with the stable parameter set to + FILE_SYNC4 or DATA_SYNC4. This is done to prevent the buffer from + being freed and reused before the data can be flushed to stable + storage on the server. + + When a response is returned from either a WRITE or a COMMIT operation + and it contains a write verifier that is different than previously + returned by the server, the client will need to retransmit all of the + buffers containing uncommitted cached data to the server. How this + is to be done is up to the implementer. If there is only one buffer + of interest, then it should probably be sent back over in a WRITE + request with the appropriate stable parameter. If there is more than + one buffer, it might be worthwhile to retransmit all of the buffers + in WRITE requests with the stable parameter set to UNSTABLE4 and then + retransmit the COMMIT operation to flush all of the data on the + server to stable storage. The timing of these retransmissions is + left to the implementer. + + The above description applies to page-cache-based systems as well as + buffer-cache-based systems. In those systems, the virtual memory + system will need to be modified instead of the buffer cache. + + + + + + + + + + + + + + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 220] + +RFC 7530 NFSv4 March 2015 + + +16.4. Operation 6: CREATE - Create a Non-regular File Object + +16.4.1. SYNOPSIS + + (cfh), name, type, attrs -> (cfh), cinfo, attrset + +16.4.2. ARGUMENT + + union createtype4 switch (nfs_ftype4 type) { + case NF4LNK: + linktext4 linkdata; + case NF4BLK: + case NF4CHR: + specdata4 devdata; + case NF4SOCK: + case NF4FIFO: + case NF4DIR: + void; + default: + void; /* server should return NFS4ERR_BADTYPE */ + }; + + struct CREATE4args { + /* CURRENT_FH: directory for creation */ + createtype4 objtype; + component4 objname; + fattr4 createattrs; + }; + +16.4.3. RESULT + + struct CREATE4resok { + change_info4 cinfo; + bitmap4 attrset; /* attributes set */ + }; + + union CREATE4res switch (nfsstat4 status) { + case NFS4_OK: + CREATE4resok resok4; + default: + void; + }; + + + + + + + + + +Haynes & Noveck Standards Track [Page 221] + +RFC 7530 NFSv4 March 2015 + + +16.4.4. DESCRIPTION + + The CREATE operation creates a non-regular file object in a directory + with a given name. The OPEN operation is used to create a regular + file. + + The objname specifies the name for the new object. The objtype + determines the type of object to be created: directory, symlink, etc. + + If an object of the same name already exists in the directory, the + server will return the error NFS4ERR_EXIST. + + For the directory where the new file object was created, the server + returns change_info4 information in cinfo. With the atomic field of + the change_info4 struct, the server will indicate if the before and + after change attributes were obtained atomically with respect to the + file object creation. + + If the objname is of zero length, NFS4ERR_INVAL will be returned. + The objname is also subject to the normal UTF-8, character support, + and name checks. See Section 12.7 for further discussion. + + The current filehandle is replaced by that of the new object. + + The createattrs field specifies the initial set of attributes for the + object. The set of attributes may include any writable attribute + valid for the object type. When the operation is successful, the + server will return to the client an attribute mask signifying which + attributes were successfully set for the object. + + If createattrs includes neither the owner attribute nor an ACL with + an ACE for the owner, and if the server's file system both supports + and requires an owner attribute (or an owner ACE), then the server + MUST derive the owner (or the owner ACE). This would typically be + from the principal indicated in the RPC credentials of the call, but + the server's operating environment or file system semantics may + dictate other methods of derivation. Similarly, if createattrs + includes neither the group attribute nor a group ACE, and if the + server's file system both supports and requires the notion of a group + attribute (or group ACE), the server MUST derive the group attribute + (or the corresponding owner ACE) for the file. This could be from + the RPC's credentials, such as the group principal if the credentials + include it (such as with AUTH_SYS), from the group identifier + associated with the principal in the credentials (e.g., POSIX systems + have a user database [getpwnam] that has the group identifier for + every user identifier), inherited from the directory the object is + + + + + +Haynes & Noveck Standards Track [Page 222] + +RFC 7530 NFSv4 March 2015 + + + created in, or whatever else the server's operating environment + or file system semantics dictate. This applies to the OPEN + operation too. + + Conversely, it is possible the client will specify in createattrs an + owner attribute, group attribute, or ACL that the principal indicated + the RPC's credentials does not have permissions to create files for. + The error to be returned in this instance is NFS4ERR_PERM. This + applies to the OPEN operation too. + +16.4.5. IMPLEMENTATION + + If the client desires to set attribute values after the create, a + SETATTR operation can be added to the COMPOUND request so that the + appropriate attributes will be set. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 223] + +RFC 7530 NFSv4 March 2015 + + +16.5. Operation 7: DELEGPURGE - Purge Delegations Awaiting Recovery + +16.5.1. SYNOPSIS + + clientid -> + +16.5.2. ARGUMENT + + struct DELEGPURGE4args { + clientid4 clientid; + }; + +16.5.3. RESULT + + struct DELEGPURGE4res { + nfsstat4 status; + }; + +16.5.4. DESCRIPTION + + DELEGPURGE purges all of the delegations awaiting recovery for a + given client. This is useful for clients that do not commit + delegation information to stable storage, to indicate that + conflicting requests need not be delayed by the server awaiting + recovery of delegation information. + + This operation is provided to support clients that record delegation + information in stable storage on the client. In this case, + DELEGPURGE should be issued immediately after doing delegation + recovery (using CLAIM_DELEGATE_PREV) on all delegations known to the + client. Doing so will notify the server that no additional + delegations for the client will be recovered, allowing it to free + resources and avoid delaying other clients who make requests that + conflict with the unrecovered delegations. All clients SHOULD use + DELEGPURGE as part of recovery once it is known that no further + CLAIM_DELEGATE_PREV recovery will be done. This includes clients + that do not record delegation information in stable storage, who + would then do a DELEGPURGE immediately after SETCLIENTID_CONFIRM. + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 224] + +RFC 7530 NFSv4 March 2015 + + + The set of delegations known to the server and the client may be + different. The reasons for this include: + + o A client may fail after making a request that resulted in + delegation but before it received the results and committed them + to the client's stable storage. + + o A client may fail after deleting its indication that a delegation + exists but before the delegation return is fully processed by the + server. + + o In the case in which the server and the client restart, the server + may have limited persistent recording of delegations to a subset + of those in existence. + + o A client may have only persistently recorded information about a + subset of delegations. + + The server MAY support DELEGPURGE, but its support or non-support + should match that of CLAIM_DELEGATE_PREV: + + o A server may support both DELEGPURGE and CLAIM_DELEGATE_PREV. + + o A server may support neither DELEGPURGE nor CLAIM_DELEGATE_PREV. + + This fact allows a client starting up to determine if the server is + prepared to support persistent storage of delegation information and + thus whether it may use write-back caching to local persistent + storage, relying on CLAIM_DELEGATE_PREV recovery to allow such + changed data to be flushed safely to the server in the event of + client restart. + + + + + + + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 225] + +RFC 7530 NFSv4 March 2015 + + +16.6. Operation 8: DELEGRETURN - Return Delegation + +16.6.1. SYNOPSIS + + (cfh), stateid -> + +16.6.2. ARGUMENT + + struct DELEGRETURN4args { + /* CURRENT_FH: delegated file */ + stateid4 deleg_stateid; + }; + +16.6.3. RESULT + + struct DELEGRETURN4res { + nfsstat4 status; + }; + +16.6.4. DESCRIPTION + + DELEGRETURN returns the delegation represented by the current + filehandle and stateid. + + Delegations may be returned when recalled or voluntarily (i.e., + before the server has recalled them). In either case, the client + must properly propagate state changed under the context of the + delegation to the server before returning the delegation. + + + + + + + + + + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 226] + +RFC 7530 NFSv4 March 2015 + + +16.7. Operation 9: GETATTR - Get Attributes + +16.7.1. SYNOPSIS + + (cfh), attrbits -> attrbits, attrvals + +16.7.2. ARGUMENT + + struct GETATTR4args { + /* CURRENT_FH: directory or file */ + bitmap4 attr_request; + }; + +16.7.3. RESULT + + struct GETATTR4resok { + fattr4 obj_attributes; + }; + + union GETATTR4res switch (nfsstat4 status) { + case NFS4_OK: + GETATTR4resok resok4; + default: + void; + }; + +16.7.4. DESCRIPTION + + The GETATTR operation will obtain attributes for the file system + object specified by the current filehandle. The client sets a bit in + the bitmap argument for each attribute value that it would like the + server to return. The server returns an attribute bitmap that + indicates the attribute values for which it was able to return + values, followed by the attribute values ordered lowest attribute + number first. + + The server MUST return a value for each attribute that the client + requests if the attribute is supported by the server. If the server + does not support an attribute or cannot approximate a useful value, + then it MUST NOT return the attribute value and MUST NOT set the + attribute bit in the result bitmap. The server MUST return an error + if it supports an attribute on the target but cannot obtain its + value. In that case, no attribute values will be returned. + + File systems that are absent should be treated as having support for + a very small set of attributes as described in Section 8.3.1 -- even + if previously, when the file system was present, more attributes were + supported. + + + +Haynes & Noveck Standards Track [Page 227] + +RFC 7530 NFSv4 March 2015 + + + All servers MUST support the REQUIRED attributes, as specified in + Section 5, for all file systems, with the exception of absent file + systems. + + On success, the current filehandle retains its value. + +16.7.5. IMPLEMENTATION + + Suppose there is an OPEN_DELEGATE_WRITE delegation held by another + client for the file in question, and size and/or change are among the + set of attributes being interrogated. The server has two choices. + First, the server can obtain the actual current value of these + attributes from the client holding the delegation by using the + CB_GETATTR callback. Second, the server, particularly when the + delegated client is unresponsive, can recall the delegation in + question. The GETATTR MUST NOT proceed until one of the following + occurs: + + o The requested attribute values are returned in the response to + CB_GETATTR. + + o The OPEN_DELEGATE_WRITE delegation is returned. + + o The OPEN_DELEGATE_WRITE delegation is revoked. + + Unless one of the above happens very quickly, one or more + NFS4ERR_DELAY errors will be returned while a delegation is + outstanding. + + + + + + + + + + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 228] + +RFC 7530 NFSv4 March 2015 + + +16.8. Operation 10: GETFH - Get Current Filehandle + +16.8.1. SYNOPSIS + + (cfh) -> filehandle + +16.8.2. ARGUMENT + + /* CURRENT_FH: */ + void; + +16.8.3. RESULT + + struct GETFH4resok { + nfs_fh4 object; + }; + + union GETFH4res switch (nfsstat4 status) { + case NFS4_OK: + GETFH4resok resok4; + default: + void; + }; + +16.8.4. DESCRIPTION + + This operation returns the current filehandle value. + + On success, the current filehandle retains its value. + +16.8.5. IMPLEMENTATION + + Operations that change the current filehandle, like LOOKUP or CREATE, + do not automatically return the new filehandle as a result. For + instance, if a client needs to look up a directory entry and obtain + its filehandle, then the following request is needed. + + PUTFH (directory filehandle) + LOOKUP (entry name) + GETFH + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 229] + +RFC 7530 NFSv4 March 2015 + + +16.9. Operation 11: LINK - Create Link to a File + +16.9.1. SYNOPSIS + + (sfh), (cfh), newname -> (cfh), cinfo + +16.9.2. ARGUMENT + + struct LINK4args { + /* SAVED_FH: source object */ + /* CURRENT_FH: target directory */ + component4 newname; + }; + +16.9.3. RESULT + + struct LINK4resok { + change_info4 cinfo; + }; + + union LINK4res switch (nfsstat4 status) { + case NFS4_OK: + LINK4resok resok4; + default: + void; + }; + +16.9.4. DESCRIPTION + + The LINK operation creates an additional newname for the file + represented by the saved filehandle, as set by the SAVEFH operation, + in the directory represented by the current filehandle. The existing + file and the target directory must reside within the same file system + on the server. On success, the current filehandle will continue to + be the target directory. If an object exists in the target directory + with the same name as newname, the server must return NFS4ERR_EXIST. + + For the target directory, the server returns change_info4 information + in cinfo. With the atomic field of the change_info4 struct, the + server will indicate if the before and after change attributes were + obtained atomically with respect to the link creation. + + If newname has a length of 0 (zero), or if newname does not obey the + UTF-8 definition, the error NFS4ERR_INVAL will be returned. + + + + + + + +Haynes & Noveck Standards Track [Page 230] + +RFC 7530 NFSv4 March 2015 + + +16.9.5. IMPLEMENTATION + + Changes to any property of the "hard" linked files are reflected in + all of the linked files. When a link is made to a file, the + attributes for the file should have a value for numlinks that is one + greater than the value before the LINK operation. + + The statement "file and the target directory must reside within the + same file system on the server" means that the fsid fields in the + attributes for the objects are the same. If they reside on different + file systems, the error NFS4ERR_XDEV is returned. This error may be + returned by some servers when there is an internal partitioning of a + file system that the LINK operation would violate. + + On some servers, "." and ".." are illegal values for newname, and the + error NFS4ERR_BADNAME will be returned if they are specified. + + When the current filehandle designates a named attribute directory + and the object to be linked (the saved filehandle) is not a named + attribute for the same object, the error NFS4ERR_XDEV MUST be + returned. When the saved filehandle designates a named attribute and + the current filehandle is not the appropriate named attribute + directory, the error NFS4ERR_XDEV MUST also be returned. + + When the current filehandle designates a named attribute directory + and the object to be linked (the saved filehandle) is a named + attribute within that directory, the server MAY return the error + NFS4ERR_NOTSUPP. + + In the case that newname is already linked to the file represented by + the saved filehandle, the server will return NFS4ERR_EXIST. + + Note that symbolic links are created with the CREATE operation. + + + + + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 231] + +RFC 7530 NFSv4 March 2015 + + +16.10. Operation 12: LOCK - Create Lock + +16.10.1. SYNOPSIS + + (cfh) locktype, reclaim, offset, length, locker -> stateid + +16.10.2. ARGUMENT + + enum nfs_lock_type4 { + READ_LT = 1, + WRITE_LT = 2, + READW_LT = 3, /* blocking read */ + WRITEW_LT = 4 /* blocking write */ + }; + + /* + * For LOCK, transition from open_owner to new lock_owner + */ + struct open_to_lock_owner4 { + seqid4 open_seqid; + stateid4 open_stateid; + seqid4 lock_seqid; + lock_owner4 lock_owner; + }; + + /* + * For LOCK, existing lock_owner continues to request file locks + */ + struct exist_lock_owner4 { + stateid4 lock_stateid; + seqid4 lock_seqid; + }; + + union locker4 switch (bool new_lock_owner) { + case TRUE: + open_to_lock_owner4 open_owner; + case FALSE: + exist_lock_owner4 lock_owner; + }; + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 232] + +RFC 7530 NFSv4 March 2015 + + + /* + * LOCK/LOCKT/LOCKU: Record lock management + */ + struct LOCK4args { + /* CURRENT_FH: file */ + nfs_lock_type4 locktype; + bool reclaim; + offset4 offset; + length4 length; + locker4 locker; + }; + +16.10.3. RESULT + + struct LOCK4denied { + offset4 offset; + length4 length; + nfs_lock_type4 locktype; + lock_owner4 owner; + }; + + struct LOCK4resok { + stateid4 lock_stateid; + }; + + union LOCK4res switch (nfsstat4 status) { + case NFS4_OK: + LOCK4resok resok4; + case NFS4ERR_DENIED: + LOCK4denied denied; + default: + void; + }; + +16.10.4. DESCRIPTION + + The LOCK operation requests a byte-range lock for the byte range + specified by the offset and length parameters. The lock type is also + specified to be one of the nfs_lock_type4s. If this is a reclaim + request, the reclaim parameter will be TRUE. + + Bytes in a file may be locked even if those bytes are not currently + allocated to the file. To lock the file from a specific offset + through the end-of-file (no matter how long the file actually is), + use a length field with all bits set to 1 (one). If the length is + zero, or if a length that is not all bits set to one is specified, + and the length when added to the offset exceeds the maximum 64-bit + unsigned integer value, the error NFS4ERR_INVAL will result. + + + +Haynes & Noveck Standards Track [Page 233] + +RFC 7530 NFSv4 March 2015 + + + 32-bit servers are servers that support locking for byte offsets that + fit within 32 bits (i.e., less than or equal to NFS4_UINT32_MAX). If + the client specifies a range that overlaps one or more bytes beyond + offset NFS4_UINT32_MAX but does not end at offset NFS4_UINT64_MAX, + then such a 32-bit server MUST return the error NFS4ERR_BAD_RANGE. + + In the case that the lock is denied, the owner, offset, and length of + a conflicting lock are returned. + + On success, the current filehandle retains its value. + +16.10.5. IMPLEMENTATION + + If the server is unable to determine the exact offset and length of + the conflicting lock, the same offset and length that were provided + in the arguments should be returned in the denied results. Section 9 + contains a full description of this and the other file locking + operations. + + LOCK operations are subject to permission checks and to checks + against the access type of the associated file. However, the + specific rights and modes required for various types of locks + reflect the semantics of the server-exported file system, and are not + specified by the protocol. For example, Windows 2000 allows a write + lock of a file open for READ, while a POSIX-compliant system + does not. + + When the client makes a lock request that corresponds to a range that + the lock-owner has locked already (with the same or different lock + type), or to a sub-region of such a range, or to a region that + includes multiple locks already granted to that lock-owner, in whole + or in part, and the server does not support such locking operations + (i.e., does not support POSIX locking semantics), the server will + return the error NFS4ERR_LOCK_RANGE. In that case, the client may + return an error, or it may emulate the required operations, using + 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 + (specifying an exactly matching range and type). Similarly, when the + client makes a lock request that amounts to upgrading (changing from + a read lock to a write lock) or downgrading (changing from a write + lock to a read lock) an existing record lock and the server does not + support such a lock, the server will return NFS4ERR_LOCK_NOTSUPP. + Such operations may not perfectly reflect the required semantics in + the face of conflicting lock requests from other clients. + + When a client holds an OPEN_DELEGATE_WRITE delegation, the client + holding that delegation is assured that there are no opens by other + clients. Thus, there can be no conflicting LOCK operations from such + + + +Haynes & Noveck Standards Track [Page 234] + +RFC 7530 NFSv4 March 2015 + + + clients. Therefore, the client may be handling locking requests + locally, without doing LOCK operations on the server. If it does + that, it must be prepared to update the lock status on the server by + sending appropriate LOCK and LOCKU operations before returning the + delegation. + + When one or more clients hold OPEN_DELEGATE_READ delegations, any + LOCK operation where the server is implementing mandatory locking + semantics MUST result in the recall of all such delegations. The + LOCK operation may not be granted until all such delegations are + returned or revoked. Except where this happens very quickly, one or + more NFS4ERR_DELAY errors will be returned to requests made while the + delegation remains outstanding. + + The locker argument specifies the lock-owner that is associated with + the LOCK request. The locker4 structure is a switched union that + indicates whether the client has already created byte-range locking + state associated with the current open file and lock-owner. There + are multiple cases to be considered, corresponding to possible + combinations of whether locking state has been created for the + current open file and lock-owner, and whether the boolean + new_lock_owner is set. In all of the cases, there is a lock_seqid + specified, whether the lock-owner is specified explicitly or + implicitly. This seqid value is used for checking lock-owner + sequencing/replay issues. When the given lock-owner is not known to + the server, this establishes an initial sequence value for the new + lock-owner. + + o In the case in which the state has been created and the boolean is + false, the only part of the argument other than lock_seqid is just + a stateid representing the set of locks associated with that open + file and lock-owner. + + o In the case in which the state has been created and the boolean is + true, the server rejects the request with the error + NFS4ERR_BAD_SEQID. The only exception is where there is a + retransmission of a previous request in which the boolean was + true. In this case, the lock_seqid will match the original + request, and the response will reflect the final case, below. + + o In the case where no byte-range locking state has been established + and the boolean is true, the argument contains an + open_to_lock_owner structure that specifies the stateid of the + open file and the lock-owner to be used for the lock. Note that + although the open-owner is not given explicitly, the open_seqid + associated with it is used to check for open-owner sequencing + issues. This case provides a method to use the established state + of the open_stateid to transition to the use of a lock stateid. + + + +Haynes & Noveck Standards Track [Page 235] + +RFC 7530 NFSv4 March 2015 + + +16.11. Operation 13: LOCKT - Test for Lock + +16.11.1. SYNOPSIS + + (cfh) locktype, offset, length, owner -> {void, NFS4ERR_DENIED -> + owner} + +16.11.2. ARGUMENT + + struct LOCKT4args { + /* CURRENT_FH: file */ + nfs_lock_type4 locktype; + offset4 offset; + length4 length; + lock_owner4 owner; + }; + +16.11.3. RESULT + + union LOCKT4res switch (nfsstat4 status) { + case NFS4ERR_DENIED: + LOCK4denied denied; + case NFS4_OK: + void; + default: + void; + }; + +16.11.4. DESCRIPTION + + The LOCKT operation tests the lock as specified in the arguments. If + a conflicting lock exists, the owner, offset, length, and type of the + conflicting lock are returned; if no lock is held, nothing other than + NFS4_OK is returned. Lock types READ_LT and READW_LT are processed + in the same way in that a conflicting lock test is done without + regard to blocking or non-blocking. The same is true for WRITE_LT + and WRITEW_LT. + + The ranges are specified as for LOCK. The NFS4ERR_INVAL and + NFS4ERR_BAD_RANGE errors are returned under the same circumstances as + for LOCK. + + On success, the current filehandle retains its value. + + + + + + + + +Haynes & Noveck Standards Track [Page 236] + +RFC 7530 NFSv4 March 2015 + + +16.11.5. IMPLEMENTATION + + If the server is unable to determine the exact offset and length of + the conflicting lock, the same offset and length that were provided + in the arguments should be returned in the denied results. Section 9 + contains further discussion of the file locking mechanisms. + + LOCKT uses a lock_owner4, rather than a stateid4 as is used in LOCK, + to identify the owner. This is because the client does not have to + open the file to test for the existence of a lock, so a stateid may + not be available. + + The test for conflicting locks SHOULD exclude locks for the current + lock-owner. Note that since such locks are not examined the possible + existence of overlapping ranges may not affect the results of LOCKT. + If the server does examine locks that match the lock-owner for the + purpose of range checking, NFS4ERR_LOCK_RANGE may be returned. In + the event that it returns NFS4_OK, clients may do a LOCK and receive + NFS4ERR_LOCK_RANGE on the LOCK request because of the flexibility + provided to the server. + + When a client holds an OPEN_DELEGATE_WRITE delegation, it may choose + (see Section 16.10.5) to handle LOCK requests locally. In such a + case, LOCKT requests will similarly be handled locally. + + + + + + + + + + + + + + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 237] + +RFC 7530 NFSv4 March 2015 + + +16.12. Operation 14: LOCKU - Unlock File + +16.12.1. SYNOPSIS + + (cfh) type, seqid, stateid, offset, length -> stateid + +16.12.2. ARGUMENT + + struct LOCKU4args { + /* CURRENT_FH: file */ + nfs_lock_type4 locktype; + seqid4 seqid; + stateid4 lock_stateid; + offset4 offset; + length4 length; + }; + +16.12.3. RESULT + + union LOCKU4res switch (nfsstat4 status) { + case NFS4_OK: + stateid4 lock_stateid; + default: + void; + }; + +16.12.4. DESCRIPTION + + The LOCKU operation unlocks the byte-range lock specified by the + parameters. The client may set the locktype field to any value that + is legal for the nfs_lock_type4 enumerated type, and the server MUST + accept any legal value for locktype. Any legal value for locktype + has no effect on the success or failure of the LOCKU operation. + + The ranges are specified as for LOCK. The NFS4ERR_INVAL and + NFS4ERR_BAD_RANGE errors are returned under the same circumstances as + for LOCK. + + On success, the current filehandle retains its value. + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 238] + +RFC 7530 NFSv4 March 2015 + + +16.12.5. IMPLEMENTATION + + If the area to be unlocked does not correspond exactly to a lock + actually held by the lock-owner, the server may return the error + NFS4ERR_LOCK_RANGE. This includes the cases where (1) the area is + not locked, (2) the area is a sub-range of the area locked, (3) it + overlaps the area locked without matching exactly, or (4) the area + specified includes multiple locks held by the lock-owner. In all of + these cases, allowed by POSIX locking [fcntl] semantics, a client + receiving this error should, if it desires support for such + operations, simulate the operation using LOCKU on ranges + corresponding to locks it actually holds, possibly followed by LOCK + requests for the sub-ranges not being unlocked. + + When a client holds an OPEN_DELEGATE_WRITE delegation, it may choose + (see Section 16.10.5) to handle LOCK requests locally. In such a + case, LOCKU requests will similarly be handled locally. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 239] + +RFC 7530 NFSv4 March 2015 + + +16.13. Operation 15: LOOKUP - Look Up Filename + +16.13.1. SYNOPSIS + + (cfh), component -> (cfh) + +16.13.2. ARGUMENT + + struct LOOKUP4args { + /* CURRENT_FH: directory */ + component4 objname; + }; + +16.13.3. RESULT + + struct LOOKUP4res { + /* CURRENT_FH: object */ + nfsstat4 status; + }; + +16.13.4. DESCRIPTION + + This operation performs a LOOKUP or finds a file system object using + the directory specified by the current filehandle. LOOKUP evaluates + the component and if the object exists the current filehandle is + replaced with the component's filehandle. + + If the component cannot be evaluated because either it does not exist + or the client does not have permission to evaluate it, then an error + will be returned, and the current filehandle will be unchanged. + + If the component is of zero length, NFS4ERR_INVAL will be returned. + The component is also subject to the normal UTF-8, character support, + and name checks. See Section 12.7 for further discussion. + + + + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 240] + +RFC 7530 NFSv4 March 2015 + + +16.13.5. IMPLEMENTATION + + If the client wants to achieve the effect of a multi-component + lookup, it may construct a COMPOUND request such as the following + (and obtain each filehandle): + + PUTFH (directory filehandle) + LOOKUP "pub" + GETFH + LOOKUP "foo" + GETFH + LOOKUP "bar" + GETFH + + NFSv4 servers depart from the semantics of previous NFS versions in + allowing LOOKUP requests to cross mount points on the server. The + client can detect a mount point crossing by comparing the fsid + attribute of the directory with the fsid attribute of the directory + looked up. If the fsids are different, then the new directory is a + server mount point. UNIX clients that detect a mount point crossing + will need to mount the server's file system. This needs to be done + to maintain the file object identity-checking mechanisms common to + UNIX clients. + + Servers that limit NFS access to "shares" or "exported" file systems + should provide a pseudo-file system into which the exported file + systems can be integrated, so that clients can browse the server's + namespace. The clients' view of a pseudo-file system will be limited + to paths that lead to exported file systems. + + Note: Previous versions of the protocol assigned special semantics to + the names "." and "..". NFSv4 assigns no special semantics to these + names. The LOOKUPP operator must be used to look up a parent + directory. + + Note that this operation does not follow symbolic links. The client + is responsible for all parsing of filenames, including filenames that + are modified by symbolic links encountered during the lookup process. + + If the current filehandle supplied is not a directory but a symbolic + link, NFS4ERR_SYMLINK is returned as the error. For all other + non-directory file types, the error NFS4ERR_NOTDIR is returned. + + + + + + + + + +Haynes & Noveck Standards Track [Page 241] + +RFC 7530 NFSv4 March 2015 + + +16.14. Operation 16: LOOKUPP - Look Up Parent Directory + +16.14.1. SYNOPSIS + + (cfh) -> (cfh) + +16.14.2. ARGUMENT + + /* CURRENT_FH: object */ + void; + +16.14.3. RESULT + + struct LOOKUPP4res { + /* CURRENT_FH: directory */ + nfsstat4 status; + }; + +16.14.4. DESCRIPTION + + The current filehandle is assumed to refer to a regular directory or + a named attribute directory. LOOKUPP assigns the filehandle for its + parent directory to be the current filehandle. If there is no parent + directory, an NFS4ERR_NOENT error must be returned. Therefore, + NFS4ERR_NOENT will be returned by the server when the current + filehandle is at the root or top of the server's file tree. + +16.14.5. IMPLEMENTATION + + As for LOOKUP, LOOKUPP will also cross mount points. + + If the current filehandle is not a directory or named attribute + directory, the error NFS4ERR_NOTDIR is returned. + + If the current filehandle is a named attribute directory that is + associated with a file system object via OPENATTR (i.e., not a + subdirectory of a named attribute directory), LOOKUPP SHOULD return + the filehandle of the associated file system object. + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 242] + +RFC 7530 NFSv4 March 2015 + + +16.15. Operation 17: NVERIFY - Verify Difference in Attributes + +16.15.1. SYNOPSIS + + (cfh), fattr -> - + +16.15.2. ARGUMENT + + struct NVERIFY4args { + /* CURRENT_FH: object */ + fattr4 obj_attributes; + }; + +16.15.3. RESULT + + struct NVERIFY4res { + nfsstat4 status; + }; + +16.15.4. DESCRIPTION + + This operation is used to prefix a sequence of operations to be + performed if one or more attributes have changed on some file system + object. If all the attributes match, then the error NFS4ERR_SAME + must be returned. + + On success, the current filehandle retains its value. + + + + + + + + + + + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 243] + +RFC 7530 NFSv4 March 2015 + + +16.15.5. IMPLEMENTATION + + This operation is useful as a cache validation operator. If the + object to which the attributes belong has changed, then the following + operations may obtain new data associated with that object -- for + instance, to check if a file has been changed and obtain new data if + it has: + + PUTFH (public) + LOOKUP "foobar" + NVERIFY attrbits attrs + READ 0 32767 + + In the case that a RECOMMENDED attribute is specified in the NVERIFY + operation and the server does not support that attribute for the file + system object, the error NFS4ERR_ATTRNOTSUPP is returned to the + client. + + When the attribute rdattr_error or any write-only attribute (e.g., + time_modify_set) is specified, the error NFS4ERR_INVAL is returned to + the client. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 244] + +RFC 7530 NFSv4 March 2015 + + +16.16. Operation 18: OPEN - Open a Regular File + +16.16.1. SYNOPSIS + + (cfh), seqid, share_access, share_deny, owner, openhow, claim -> + (cfh), stateid, cinfo, rflags, attrset, delegation + +16.16.2. ARGUMENT + + /* + * Various definitions for OPEN + */ + enum createmode4 { + UNCHECKED4 = 0, + GUARDED4 = 1, + EXCLUSIVE4 = 2 + }; + + union createhow4 switch (createmode4 mode) { + case UNCHECKED4: + case GUARDED4: + fattr4 createattrs; + case EXCLUSIVE4: + verifier4 createverf; + }; + + enum opentype4 { + OPEN4_NOCREATE = 0, + OPEN4_CREATE = 1 + }; + + union openflag4 switch (opentype4 opentype) { + case OPEN4_CREATE: + createhow4 how; + default: + void; + }; + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 245] + +RFC 7530 NFSv4 March 2015 + + + /* Next definitions used for OPEN delegation */ + enum limit_by4 { + NFS_LIMIT_SIZE = 1, + NFS_LIMIT_BLOCKS = 2 + /* others as needed */ + }; + + struct nfs_modified_limit4 { + uint32_t num_blocks; + uint32_t bytes_per_block; + }; + + union nfs_space_limit4 switch (limit_by4 limitby) { + /* limit specified as file size */ + case NFS_LIMIT_SIZE: + uint64_t filesize; + /* limit specified by number of blocks */ + case NFS_LIMIT_BLOCKS: + nfs_modified_limit4 mod_blocks; + }; + + enum open_delegation_type4 { + OPEN_DELEGATE_NONE = 0, + OPEN_DELEGATE_READ = 1, + OPEN_DELEGATE_WRITE = 2 + }; + + enum open_claim_type4 { + CLAIM_NULL = 0, + CLAIM_PREVIOUS = 1, + CLAIM_DELEGATE_CUR = 2, + CLAIM_DELEGATE_PREV = 3 + }; + + struct open_claim_delegate_cur4 { + stateid4 delegate_stateid; + component4 file; + }; + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 246] + +RFC 7530 NFSv4 March 2015 + + + union open_claim4 switch (open_claim_type4 claim) { + /* + * No special rights to file. + * Ordinary OPEN of the specified file. + */ + case CLAIM_NULL: + /* CURRENT_FH: directory */ + component4 file; + /* + * Right to the file established by an + * open previous to server reboot. File + * identified by filehandle obtained at + * that time rather than by name. + */ + case CLAIM_PREVIOUS: + /* CURRENT_FH: file being reclaimed */ + open_delegation_type4 delegate_type; + + /* + * Right to file based on a delegation + * granted by the server. File is + * specified by name. + */ + case CLAIM_DELEGATE_CUR: + /* CURRENT_FH: directory */ + open_claim_delegate_cur4 delegate_cur_info; + + /* + * Right to file based on a delegation + * granted to a previous boot instance + * of the client. File is specified by name. + */ + case CLAIM_DELEGATE_PREV: + /* CURRENT_FH: directory */ + component4 file_delegate_prev; + }; + + /* + * OPEN: Open a file, potentially receiving an open delegation + */ + struct OPEN4args { + seqid4 seqid; + uint32_t share_access; + uint32_t share_deny; + open_owner4 owner; + openflag4 openhow; + open_claim4 claim; + }; + + + +Haynes & Noveck Standards Track [Page 247] + +RFC 7530 NFSv4 March 2015 + + +16.16.3. RESULT + + struct open_read_delegation4 { + stateid4 stateid; /* Stateid for delegation */ + bool recall; /* Pre-recalled flag for + delegations obtained + by reclaim (CLAIM_PREVIOUS) */ + + nfsace4 permissions; /* Defines users who don't + need an ACCESS call to + open for read */ + }; + + struct open_write_delegation4 { + stateid4 stateid; /* Stateid for delegation */ + bool recall; /* Pre-recalled flag for + delegations obtained + by reclaim + (CLAIM_PREVIOUS) */ + + nfs_space_limit4 + space_limit; /* Defines condition that + the client must check to + determine whether the + file needs to be flushed + to the server on close */ + + nfsace4 permissions; /* Defines users who don't + need an ACCESS call as + part of a delegated + open */ + }; + + union open_delegation4 switch + (open_delegation_type4 delegation_type) { + case OPEN_DELEGATE_NONE: + void; + case OPEN_DELEGATE_READ: + open_read_delegation4 read; + case OPEN_DELEGATE_WRITE: + open_write_delegation4 write; + }; + + /* + * Result flags + */ + + + + + +Haynes & Noveck Standards Track [Page 248] + +RFC 7530 NFSv4 March 2015 + + + /* Client must confirm open */ + const OPEN4_RESULT_CONFIRM = 0x00000002; + /* Type of file locking behavior at the server */ + const OPEN4_RESULT_LOCKTYPE_POSIX = 0x00000004; + + struct OPEN4resok { + stateid4 stateid; /* Stateid for open */ + change_info4 cinfo; /* Directory change info */ + uint32_t rflags; /* Result flags */ + bitmap4 attrset; /* attribute set for create */ + open_delegation4 delegation; /* Info on any open + delegation */ + }; + + union OPEN4res switch (nfsstat4 status) { + case NFS4_OK: + /* CURRENT_FH: opened file */ + OPEN4resok resok4; + default: + void; + }; + +16.16.4. Warning to Client Implementers + + OPEN resembles LOOKUP in that it generates a filehandle for the + client to use. Unlike LOOKUP, though, OPEN creates server state on + the filehandle. In normal circumstances, the client can only release + this state with a CLOSE operation. CLOSE uses the current filehandle + to determine which file to close. Therefore, the client MUST follow + every OPEN operation with a GETFH operation in the same COMPOUND + procedure. This will supply the client with the filehandle such that + CLOSE can be used appropriately. + + Simply waiting for the lease on the file to expire is insufficient + because the server may maintain the state indefinitely as long as + another client does not attempt to make a conflicting access to the + same file. + +16.16.5. DESCRIPTION + + The OPEN operation creates and/or opens a regular file in a directory + with the provided name. If the file does not exist at the server and + creation is desired, specification of the method of creation is + provided by the openhow parameter. The client has the choice of + three creation methods: UNCHECKED4, GUARDED4, or EXCLUSIVE4. + + + + + + +Haynes & Noveck Standards Track [Page 249] + +RFC 7530 NFSv4 March 2015 + + + If the current filehandle is a named attribute directory, OPEN will + then create or open a named attribute file. Note that exclusive + create of a named attribute is not supported. If the createmode is + EXCLUSIVE4 and the current filehandle is a named attribute directory, + the server will return EINVAL. + + UNCHECKED4 means that the file should be created if a file of that + name does not exist and encountering an existing regular file of that + name is not an error. For this type of create, createattrs specifies + the initial set of attributes for the file. The set of attributes + may include any writable attribute valid for regular files. When an + UNCHECKED4 create encounters an existing file, the attributes + specified by createattrs are not used, except that when a size of + zero is specified, the existing file is truncated. If GUARDED4 is + specified, the server checks for the presence of a duplicate object + by name before performing the create. If a duplicate exists, an + error of NFS4ERR_EXIST is returned as the status. If the object does + not exist, the request is performed as described for UNCHECKED4. For + each of these cases (UNCHECKED4 and GUARDED4), where the operation is + successful, the server will return to the client an attribute mask + signifying which attributes were successfully set for the object. + + EXCLUSIVE4 specifies that the server is to follow exclusive creation + semantics, using the verifier to ensure exclusive creation of the + target. The server should check for the presence of a duplicate + object by name. If the object does not exist, the server creates the + object and stores the verifier with the object. If the object does + exist and the stored verifier matches the verifier provided by the + client, the server uses the existing object as the newly created + object. If the stored verifier does not match, then an error of + NFS4ERR_EXIST is returned. No attributes may be provided in this + case, since the server may use an attribute of the target object to + store the verifier. If the server uses an attribute to store the + exclusive create verifier, it will signify which attribute was used + by setting the appropriate bit in the attribute mask that is returned + in the results. + + For the target directory, the server returns change_info4 information + in cinfo. With the atomic field of the change_info4 struct, the + server will indicate if the before and after change attributes were + obtained atomically with respect to the link creation. + + Upon successful creation, the current filehandle is replaced by that + of the new object. + + The OPEN operation provides for Windows share reservation capability + with the use of the share_access and share_deny fields of the OPEN + arguments. The client specifies at OPEN the required share_access + + + +Haynes & Noveck Standards Track [Page 250] + +RFC 7530 NFSv4 March 2015 + + + and share_deny modes. For clients that do not directly support + SHAREs (i.e., UNIX), the expected deny value is DENY_NONE. In the + case that there is an existing share reservation that conflicts with + the OPEN request, the server returns the error NFS4ERR_SHARE_DENIED. + For a complete SHARE request, the client must provide values for the + owner and seqid fields for the OPEN argument. For additional + discussion of share semantics, see Section 9.9. + + In the case that the client is recovering state from a server + failure, the claim field of the OPEN argument is used to signify that + the request is meant to reclaim state previously held. + + The claim field of the OPEN argument is used to specify the file to + be opened and the state information that the client claims to + possess. There are four basic claim types that cover the various + situations for an OPEN. They are as follows: + + CLAIM_NULL: For the client, this is a new OPEN request, and there is + no previous state associated with the file for the client. + + CLAIM_PREVIOUS: The client is claiming basic OPEN state for a file + that was held previous to a server reboot. This is generally used + when a server is returning persistent filehandles; the client may + not have the filename to reclaim the OPEN. + + CLAIM_DELEGATE_CUR: The client is claiming a delegation for OPEN as + granted by the server. This is generally done as part of + recalling a delegation. + + CLAIM_DELEGATE_PREV: The client is claiming a delegation granted to + a previous client instance. This claim type is for use after a + SETCLIENTID_CONFIRM and before the corresponding DELEGPURGE in two + situations: after a client reboot and after a lease expiration + that resulted in loss of all lock state. The server MAY support + CLAIM_DELEGATE_PREV. If it does support CLAIM_DELEGATE_PREV, + SETCLIENTID_CONFIRM MUST NOT remove the client's delegation state, + and the server MUST support the DELEGPURGE operation. + + The following errors apply to use of the CLAIM_DELEGATE_PREV claim + type: + + o NFS4ERR_NOTSUPP is returned if the server does not support this + claim type. + + o NFS4ERR_INVAL is returned if the reclaim is done at an + inappropriate time, e.g., after DELEGPURGE has been done. + + + + + +Haynes & Noveck Standards Track [Page 251] + +RFC 7530 NFSv4 March 2015 + + + o NFS4ERR_BAD_RECLAIM is returned if the other error conditions do + not apply and the server has no record of the delegation whose + reclaim is being attempted. + + For OPEN requests whose claim type is other than CLAIM_PREVIOUS + (i.e., requests other than those devoted to reclaiming opens after a + server reboot) that reach the server during its grace or lease + expiration period, the server returns an error of NFS4ERR_GRACE. + + For any OPEN request, the server may return an open delegation, which + allows further opens and closes to be handled locally on the client + as described in Section 10.4. Note that delegation is up to the + server to decide. The client should never assume that delegation + will or will not be granted in a particular instance. It should + always be prepared for either case. A partial exception is the + reclaim (CLAIM_PREVIOUS) case, in which a delegation type is claimed. + In this case, delegation will always be granted, although the server + may specify an immediate recall in the delegation structure. + + The rflags returned by a successful OPEN allow the server to return + information governing how the open file is to be handled. + + OPEN4_RESULT_CONFIRM indicates that the client MUST execute an + OPEN_CONFIRM operation before using the open file. + OPEN4_RESULT_LOCKTYPE_POSIX indicates that the server's file locking + behavior supports the complete set of POSIX locking techniques + [fcntl]. From this, the client can choose to manage file locking + state in such a way as to handle a mismatch of file locking + management. + + If the component is of zero length, NFS4ERR_INVAL will be returned. + The component is also subject to the normal UTF-8, character support, + and name checks. See Section 12.7 for further discussion. + + When an OPEN is done and the specified open-owner already has the + resulting filehandle open, the result is to "OR" together the new + share and deny status, together with the existing status. In this + case, only a single CLOSE need be done, even though multiple OPENs + were completed. When such an OPEN is done, checking of share + reservations for the new OPEN proceeds normally, with no exception + for the existing OPEN held by the same owner. In this case, the + stateid returned has an "other" field that matches that of the + previous open, while the seqid field is incremented to reflect the + changed status due to the new open (Section 9.1.4). + + + + + + + +Haynes & Noveck Standards Track [Page 252] + +RFC 7530 NFSv4 March 2015 + + + If the underlying file system at the server is only accessible in a + read-only mode and the OPEN request has specified + OPEN4_SHARE_ACCESS_WRITE or OPEN4_SHARE_ACCESS_BOTH, the server will + return NFS4ERR_ROFS to indicate a read-only file system. + + As with the CREATE operation, the server MUST derive the owner, owner + ACE, group, or group ACE if any of the four attributes are required + and supported by the server's file system. For an OPEN with the + EXCLUSIVE4 createmode, the server has no choice, since such OPEN + calls do not include the createattrs field. Conversely, if + createattrs is specified and includes owner or group (or + corresponding ACEs) that the principal in the RPC's credentials does + not have authorization to create files for, then the server may + return NFS4ERR_PERM. + + In the case where an OPEN specifies a size of zero (e.g., truncation) + and the file has named attributes, the named attributes are left as + is. They are not removed. + +16.16.6. IMPLEMENTATION + + The OPEN operation contains support for EXCLUSIVE4 create. The + mechanism is similar to the support in NFSv3 [RFC1813]. As in NFSv3, + this mechanism provides reliable exclusive creation. Exclusive + create is invoked when the how parameter is EXCLUSIVE4. In this + case, the client provides a verifier that can reasonably be expected + to be unique. A combination of a client identifier, perhaps the + client network address, and a unique number generated by the client, + perhaps the RPC transaction identifier, may be appropriate. + + If the object does not exist, the server creates the object and + stores the verifier in stable storage. For file systems that do not + provide a mechanism for the storage of arbitrary file attributes, the + server may use one or more elements of the object metadata to store + the verifier. The verifier must be stored in stable storage to + prevent erroneous failure on retransmission of the request. It is + assumed that an exclusive create is being performed because exclusive + semantics are critical to the application. Because of the expected + usage, exclusive create does not rely solely on the normally volatile + duplicate request cache for storage of the verifier. The duplicate + request cache in volatile storage does not survive a crash and may + actually flush on a long network partition, opening failure windows. + In the UNIX local file system environment, the expected storage + location for the verifier on creation is the metadata (timestamps) of + the object. For this reason, an exclusive object create may not + include initial attributes because the server would have nowhere to + store the verifier. + + + + +Haynes & Noveck Standards Track [Page 253] + +RFC 7530 NFSv4 March 2015 + + + If the server cannot support these exclusive create semantics, + possibly because of the requirement to commit the verifier to stable + storage, it should fail the OPEN request with the error + NFS4ERR_NOTSUPP. + + During an exclusive CREATE request, if the object already exists, the + server reconstructs the object's verifier and compares it with the + verifier in the request. If they match, the server treats the + request as a success. The request is presumed to be a duplicate of + an earlier, successful request for which the reply was lost and that + the server duplicate request cache mechanism did not detect. If the + verifiers do not match, the request is rejected with the status + NFS4ERR_EXIST. + + Once the client has performed a successful exclusive create, it must + issue a SETATTR to set the correct object attributes. Until it does + so, it should not rely upon any of the object attributes, since the + server implementation may need to overload object metadata to store + the verifier. The subsequent SETATTR must not occur in the same + COMPOUND request as the OPEN. This separation will guarantee that + the exclusive create mechanism will continue to function properly in + the face of retransmission of the request. + + Use of the GUARDED4 attribute does not provide "exactly-once" + semantics. In particular, if a reply is lost and the server does not + detect the retransmission of the request, the operation can fail with + NFS4ERR_EXIST, even though the create was performed successfully. + The client would use this behavior in the case that the application + has not requested an exclusive create but has asked to have the file + truncated when the file is opened. In the case of the client timing + out and retransmitting the create request, the client can use + GUARDED4 to prevent a sequence such as create, write, create + (retransmitted) from occurring. + + For share reservations (see Section 9.9), the client must specify a + value for share_access that is one of OPEN4_SHARE_ACCESS_READ, + OPEN4_SHARE_ACCESS_WRITE, or OPEN4_SHARE_ACCESS_BOTH. For + share_deny, the client must specify one of OPEN4_SHARE_DENY_NONE, + OPEN4_SHARE_DENY_READ, OPEN4_SHARE_DENY_WRITE, or + OPEN4_SHARE_DENY_BOTH. If the client fails to do this, the server + must return NFS4ERR_INVAL. + + Based on the share_access value (OPEN4_SHARE_ACCESS_READ, + OPEN4_SHARE_ACCESS_WRITE, or OPEN4_SHARE_ACCESS_BOTH), the client + should check that the requester has the proper access rights to + perform the specified operation. This would generally be the results + of applying the ACL access rules to the file for the current + requester. However, just as with the ACCESS operation, the client + + + +Haynes & Noveck Standards Track [Page 254] + +RFC 7530 NFSv4 March 2015 + + + should not attempt to second-guess the server's decisions, as access + rights may change and may be subject to server administrative + controls outside the ACL framework. If the requester is not + authorized to READ or WRITE (depending on the share_access value), + the server must return NFS4ERR_ACCESS. Note that since the NFSv4 + protocol does not impose any requirement that READs and WRITEs issued + for an open file have the same credentials as the OPEN itself, the + server still must do appropriate access checking on the READs and + WRITEs themselves. + + If the component provided to OPEN resolves to something other than a + regular file (or a named attribute), an error will be returned to the + client. If it is a directory, NFS4ERR_ISDIR is returned; otherwise, + NFS4ERR_SYMLINK is returned. Note that NFS4ERR_SYMLINK is returned + for both symlinks and for special files of other types; NFS4ERR_INVAL + would be inappropriate, since the arguments provided by the client + were correct, and the client cannot necessarily know at the time it + sent the OPEN that the component would resolve to a non-regular file. + + If the current filehandle is not a directory, the error + NFS4ERR_NOTDIR will be returned. + + If a COMPOUND contains an OPEN that establishes an + OPEN_DELEGATE_WRITE delegation, then subsequent GETATTRs normally + result in a CB_GETATTR being sent to the client holding the + delegation. However, in the case in which the OPEN and GETATTR are + part of the same COMPOUND, the server SHOULD understand that the + operations are for the same client ID and avoid querying the client, + which will not be able to respond. This sequence of OPEN and GETATTR + SHOULD be understood to be the retrieval of the size and change + attributes at the time of OPEN. Further, as explained in + Section 15.2.5, the client should not construct a COMPOUND that mixes + operations for different client IDs. + + + + + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 255] + +RFC 7530 NFSv4 March 2015 + + +16.17. Operation 19: OPENATTR - Open Named Attribute Directory + +16.17.1. SYNOPSIS + + (cfh) createdir -> (cfh) + +16.17.2. ARGUMENT + + struct OPENATTR4args { + /* CURRENT_FH: object */ + bool createdir; + }; + +16.17.3. RESULT + + struct OPENATTR4res { + /* CURRENT_FH: named attr directory */ + nfsstat4 status; + }; + +16.17.4. DESCRIPTION + + The OPENATTR operation is used to obtain the filehandle of the named + attribute directory associated with the current filehandle. The + result of the OPENATTR will be a filehandle to an object of type + NF4ATTRDIR. From this filehandle, READDIR and LOOKUP operations can + be used to obtain filehandles for the various named attributes + associated with the original file system object. Filehandles + returned within the named attribute directory will have a type of + NF4NAMEDATTR. + + The createdir argument allows the client to signify if a named + attribute directory should be created as a result of the OPENATTR + operation. Some clients may use the OPENATTR operation with a value + of FALSE for createdir to determine if any named attributes exist for + the object. If none exist, then NFS4ERR_NOENT will be returned. If + createdir has a value of TRUE and no named attribute directory + exists, one is created. The creation of a named attribute directory + assumes that the server has implemented named attribute support in + this fashion and is not required to do so by this definition. + +16.17.5. IMPLEMENTATION + + If the server does not support named attributes for the current + filehandle, an error of NFS4ERR_NOTSUPP will be returned to the + client. + + + + + +Haynes & Noveck Standards Track [Page 256] + +RFC 7530 NFSv4 March 2015 + + +16.18. Operation 20: OPEN_CONFIRM - Confirm Open + +16.18.1. SYNOPSIS + + (cfh), seqid, stateid -> stateid + +16.18.2. ARGUMENT + + struct OPEN_CONFIRM4args { + /* CURRENT_FH: opened file */ + stateid4 open_stateid; + seqid4 seqid; + }; + +16.18.3. RESULT + + struct OPEN_CONFIRM4resok { + stateid4 open_stateid; + }; + + union OPEN_CONFIRM4res switch (nfsstat4 status) { + case NFS4_OK: + OPEN_CONFIRM4resok resok4; + default: + void; + }; + +16.18.4. DESCRIPTION + + This operation is used to confirm the sequence id usage for the first + time that an open-owner is used by a client. The stateid returned + 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 + passed to the OPEN_CONFIRM must be 1 (one) greater than the seqid + passed to the OPEN operation (Section 9.1.4). If the server receives + an unexpected sequence id with respect to the original OPEN, then the + server assumes that the client will not confirm the original OPEN and + all state associated with the original OPEN is released by the + server. + + On success, the current filehandle retains its value. + +16.18.5. IMPLEMENTATION + + A given client might generate many open_owner4 data structures for a + given client ID. The client will periodically either dispose of its + open_owner4s or stop using them for indefinite periods of time. The + latter situation is why the NFSv4 protocol does not have an explicit + + + +Haynes & Noveck Standards Track [Page 257] + +RFC 7530 NFSv4 March 2015 + + + operation to exit an open_owner4: such an operation is of no use in + that situation. Instead, to avoid unbounded memory use, the server + needs to implement a strategy for disposing of open_owner4s that have + no current open state for any files and have not been used recently. + The time period used to determine when to dispose of open_owner4s is + an implementation choice. The time period should certainly be no + less than the lease time plus any grace period the server wishes to + implement beyond a lease time. The OPEN_CONFIRM operation allows the + server to safely dispose of unused open_owner4 data structures. + + In the case that a client issues an OPEN operation and the server no + longer has a record of the open_owner4, the server needs to ensure + that this is a new OPEN and not a replay or retransmission. + + Servers MUST NOT require confirmation on OPENs that grant delegations + or are doing reclaim operations. See Section 9.1.11 for details. + The server can easily avoid this by noting whether it has disposed of + one open_owner4 for the given client ID. If the server does not + support delegation, it might simply maintain a single bit that notes + whether any open_owner4 (for any client) has been disposed of. + + The server must hold unconfirmed OPEN state until one of three events + occurs. First, the client sends an OPEN_CONFIRM request with the + appropriate sequence id and stateid within the lease period. In this + case, the OPEN state on the server goes to confirmed, and the + open_owner4 on the server is fully established. + + Second, the client sends another OPEN request with a sequence id that + is incorrect for the open_owner4 (out of sequence). In this case, + the server assumes the second OPEN request is valid and the first one + is a replay. The server cancels the OPEN state of the first OPEN + request, establishes an unconfirmed OPEN state for the second OPEN + request, and responds to the second OPEN request with an indication + that an OPEN_CONFIRM is needed. The process then repeats itself. + While there is a potential for a denial-of-service attack on the + client, it is mitigated if the client and server require the use of a + security flavor based on Kerberos V5 or some other flavor that uses + cryptography. + + What if the server is in the unconfirmed OPEN state for a given + open_owner4, and it receives an operation on the open_owner4 that has + a stateid but the operation is not OPEN, or it is OPEN_CONFIRM but + with the wrong stateid? Then, even if the seqid is correct, the + server returns NFS4ERR_BAD_STATEID, because the server assumes the + operation is a replay: if the server has no established OPEN state, + then there is no way, for example, a LOCK operation could be valid. + + + + + +Haynes & Noveck Standards Track [Page 258] + +RFC 7530 NFSv4 March 2015 + + + Third, neither of the two aforementioned events occurs for the + open_owner4 within the lease period. In this case, the OPEN state is + canceled and disposal of the open_owner4 can occur. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 259] + +RFC 7530 NFSv4 March 2015 + + +16.19. Operation 21: OPEN_DOWNGRADE - Reduce Open File Access + +16.19.1. SYNOPSIS + + (cfh), stateid, seqid, access, deny -> stateid + +16.19.2. ARGUMENT + + struct OPEN_DOWNGRADE4args { + /* CURRENT_FH: opened file */ + stateid4 open_stateid; + seqid4 seqid; + uint32_t share_access; + uint32_t share_deny; + }; + +16.19.3. RESULT + + struct OPEN_DOWNGRADE4resok { + stateid4 open_stateid; + }; + + union OPEN_DOWNGRADE4res switch (nfsstat4 status) { + case NFS4_OK: + OPEN_DOWNGRADE4resok resok4; + default: + void; + }; + + + + + + + + + + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 260] + +RFC 7530 NFSv4 March 2015 + + +16.19.4. DESCRIPTION + + This operation is used to adjust the share_access and share_deny bits + for a given open. This is necessary when a given open-owner opens + the same file multiple times with different share_access and + share_deny flags. In this situation, a close of one of the opens may + change the appropriate share_access and share_deny flags to remove + bits associated with opens no longer in effect. + + The share_access and share_deny bits specified in this operation + replace the current ones for the specified open file. The + share_access and share_deny bits specified must be exactly equal to + the union of the share_access and share_deny bits specified for some + subset of the OPENs in effect for the current open-owner on the + current file. If that constraint is not respected, the error + NFS4ERR_INVAL should be returned. Since share_access and share_deny + bits are subsets of those already granted, it is not possible for + this request to be denied because of conflicting share reservations. + + As the OPEN_DOWNGRADE may change a file to be not-open-for-write and + a write byte-range lock might be held, the server may have to reject + the OPEN_DOWNGRADE with an NFS4ERR_LOCKS_HELD. + + On success, the current filehandle retains its value. + + + + + + + + + + + + + + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 261] + +RFC 7530 NFSv4 March 2015 + + +16.20. Operation 22: PUTFH - Set Current Filehandle + +16.20.1. SYNOPSIS + + filehandle -> (cfh) + +16.20.2. ARGUMENT + + struct PUTFH4args { + nfs_fh4 object; + }; + +16.20.3. RESULT + + struct PUTFH4res { + /* CURRENT_FH: */ + nfsstat4 status; + }; + +16.20.4. DESCRIPTION + + PUTFH replaces the current filehandle with the filehandle provided as + an argument. + + If the security mechanism used by the requester does not meet the + requirements of the filehandle provided to this operation, the server + MUST return NFS4ERR_WRONGSEC. + + See Section 15.2.4.1 for more details on the current filehandle. + +16.20.5. IMPLEMENTATION + + PUTFH is commonly used as the first operator in an NFS request to set + the context for operations that follow it. + + + + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 262] + +RFC 7530 NFSv4 March 2015 + + +16.21. Operation 23: PUTPUBFH - Set Public Filehandle + +16.21.1. SYNOPSIS + + - -> (cfh) + +16.21.2. ARGUMENT + + void; + +16.21.3. RESULT + + struct PUTPUBFH4res { + /* CURRENT_FH: public fh */ + nfsstat4 status; + }; + +16.21.4. DESCRIPTION + + PUTPUBFH replaces the current filehandle with the filehandle that + represents the public filehandle of the server's namespace. This + filehandle may be different from the root filehandle, which may be + associated with some other directory on the server. + + The public filehandle concept was introduced in [RFC2054], [RFC2055], + and [RFC2224]. The intent for NFSv4 is that the public filehandle + (represented by the PUTPUBFH operation) be used as a method of + providing compatibility with the WebNFS server of NFSv2 and NFSv3. + + The public filehandle and the root filehandle (represented by the + PUTROOTFH operation) should be equivalent. If the public and root + filehandles are not equivalent, then the public filehandle MUST be a + descendant of the root filehandle. + + + + + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 263] + +RFC 7530 NFSv4 March 2015 + + +16.21.5. IMPLEMENTATION + + PUTPUBFH is used as the first operator in an NFS request to set the + context for operations that follow it. + + With the NFSv2 and NFSv3 public filehandle, the client is able to + specify whether the pathname provided in the LOOKUP should be + evaluated as either an absolute path relative to the server's root or + relative to the public filehandle. [RFC2224] contains further + discussion of the functionality. With NFSv4, that type of + specification is not directly available in the LOOKUP operation. The + reason for this is because the component separators needed to specify + absolute versus relative are not allowed in NFSv4. Therefore, the + client is responsible for constructing its request such that either + PUTROOTFH or PUTPUBFH is used to signify absolute or relative + evaluation of an NFS URL, respectively. + + Note that there are warnings mentioned in [RFC2224] with respect to + the use of absolute evaluation and the restrictions the server may + place on that evaluation with respect to how much of its namespace + has been made available. These same warnings apply to NFSv4. It is + likely, therefore, that because of server implementation details an + NFSv3 absolute public filehandle lookup may behave differently than + an NFSv4 absolute resolution. + + There is a form of security negotiation as described in [RFC2755] + that uses the public filehandle as a method of employing the Simple + and Protected GSS-API Negotiation Mechanism (SNEGO) [RFC4178]. This + method is not available with NFSv4, as filehandles are not overloaded + with special meaning and therefore do not provide the same framework + as NFSv2 and NFSv3. Clients should therefore use the security + negotiation mechanisms described in this RFC. + + + + + + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 264] + +RFC 7530 NFSv4 March 2015 + + +16.22. Operation 24: PUTROOTFH - Set Root Filehandle + +16.22.1. SYNOPSIS + + - -> (cfh) + +16.22.2. ARGUMENT + + void; + +16.22.3. RESULT + + struct PUTROOTFH4res { + /* CURRENT_FH: root fh */ + nfsstat4 status; + }; + +16.22.4. DESCRIPTION + + PUTROOTFH replaces the current filehandle with the filehandle that + represents the root of the server's namespace. From this filehandle, + a LOOKUP operation can locate any other filehandle on the server. + This filehandle may be different from the public filehandle, which + may be associated with some other directory on the server. + + See Section 15.2.4.1 for more details on the current filehandle. + +16.22.5. IMPLEMENTATION + + PUTROOTFH is commonly used as the first operator in an NFS request to + set the context for operations that follow it. + + + + + + + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 265] + +RFC 7530 NFSv4 March 2015 + + +16.23. Operation 25: READ - Read from File + +16.23.1. SYNOPSIS + + (cfh), stateid, offset, count -> eof, data + +16.23.2. ARGUMENT + + struct READ4args { + /* CURRENT_FH: file */ + stateid4 stateid; + offset4 offset; + count4 count; + }; + +16.23.3. RESULT + + struct READ4resok { + bool eof; + opaque data<>; + }; + + union READ4res switch (nfsstat4 status) { + case NFS4_OK: + READ4resok resok4; + default: + void; + }; + +16.23.4. DESCRIPTION + + The READ operation reads data from the regular file identified by the + current filehandle. + + The client provides an offset of where the READ is to start and a + count of how many bytes are to be read. An offset of 0 (zero) means + to read data starting at the beginning of the file. If the offset is + greater than or equal to the size of the file, the status, NFS4_OK, + is returned with a data length set to 0 (zero), and eof is set to + TRUE. The READ is subject to access permissions checking. + + If the client specifies a count value of 0 (zero), the READ succeeds + and returns 0 (zero) bytes of data (subject to access permissions + checking). The server may choose to return fewer bytes than + specified by the client. The client needs to check for this + condition and handle the condition appropriately. + + + + + +Haynes & Noveck Standards Track [Page 266] + +RFC 7530 NFSv4 March 2015 + + + The stateid value for a READ request represents a value returned from + a previous byte-range lock or share reservation request, or the + stateid associated with a delegation. The stateid is used by the + server to verify that the associated share reservation and any + byte-range locks are still valid and to update lease timeouts for the + client. + + If the READ ended at the end-of-file (formally, in a correctly formed + READ request, if offset + count is equal to the size of the file), or + the READ request extends beyond the size of the file (if offset + + count is greater than the size of the file), eof is returned as TRUE; + otherwise, it is FALSE. A successful READ of an empty file will + always return eof as TRUE. + + If the current filehandle is not a regular file, an error will be + returned to the client. In the case where the current filehandle + represents a directory, NFS4ERR_ISDIR is returned; otherwise, + NFS4ERR_INVAL is returned. + + For a READ using the special anonymous stateid, the server MAY allow + the READ to be serviced subject to mandatory file locks or the + current share_deny modes for the file. For a READ using the special + READ bypass stateid, the server MAY allow READ operations to bypass + locking checks at the server. + + On success, the current filehandle retains its value. + +16.23.5. IMPLEMENTATION + + If the server returns a "short read" (i.e., less data than requested + and eof is set to FALSE), the client should send another READ to get + the remaining data. A server may return less data than requested + under several circumstances. The file may have been truncated by + another client or perhaps on the server itself, changing the file + size from what the requesting client believes to be the case. This + would reduce the actual amount of data available to the client. It + is possible that the server reduces the transfer size and so returns + a short read result. Server resource exhaustion may also result in a + short read. + + If mandatory byte-range locking is in effect for the file, and if the + byte range corresponding to the data to be read from the file is + WRITE_LT locked by an owner not associated with the stateid, the + server will return the NFS4ERR_LOCKED error. The client should try + to get the appropriate READ_LT via the LOCK operation before + re-attempting the READ. When the READ completes, the client should + release the byte-range lock via LOCKU. + + + + +Haynes & Noveck Standards Track [Page 267] + +RFC 7530 NFSv4 March 2015 + + + If another client has an OPEN_DELEGATE_WRITE delegation for the file + being read, the delegation must be recalled, and the operation cannot + proceed until that delegation is returned or revoked. Except where + this happens very quickly, one or more NFS4ERR_DELAY errors will be + returned to requests made while the delegation remains outstanding. + Normally, delegations will not be recalled as a result of a READ + operation, since the recall will occur as a result of an earlier + OPEN. However, since it is possible for a READ to be done with a + special stateid, the server needs to check for this case even though + the client should have done an OPEN previously. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 268] + +RFC 7530 NFSv4 March 2015 + + +16.24. Operation 26: READDIR - Read Directory + +16.24.1. SYNOPSIS + + (cfh), cookie, cookieverf, dircount, maxcount, attr_request -> + cookieverf { cookie, name, attrs } + +16.24.2. ARGUMENT + + struct READDIR4args { + /* CURRENT_FH: directory */ + nfs_cookie4 cookie; + verifier4 cookieverf; + count4 dircount; + count4 maxcount; + bitmap4 attr_request; + }; + +16.24.3. RESULT + + struct entry4 { + nfs_cookie4 cookie; + component4 name; + fattr4 attrs; + entry4 *nextentry; + }; + + struct dirlist4 { + entry4 *entries; + bool eof; + }; + + struct READDIR4resok { + verifier4 cookieverf; + dirlist4 reply; + }; + + union READDIR4res switch (nfsstat4 status) { + case NFS4_OK: + READDIR4resok resok4; + default: + void; + }; + + + + + + + + +Haynes & Noveck Standards Track [Page 269] + +RFC 7530 NFSv4 March 2015 + + +16.24.4. DESCRIPTION + + The READDIR operation retrieves a variable number of entries from a + file system directory and for each entry returns attributes that were + requested by the client, along with information to allow the client + to request additional directory entries in a subsequent READDIR. + + The arguments contain a cookie value that represents where the + READDIR should start within the directory. A value of 0 (zero) for + the cookie is used to start reading at the beginning of the + directory. For subsequent READDIR requests, the client specifies a + cookie value that is provided by the server in a previous READDIR + request. + + The cookieverf value should be set to 0 (zero) when the cookie value + is 0 (zero) (first directory read). On subsequent requests, it + should be a cookieverf as returned by the server. The cookieverf + must match that returned by the READDIR in which the cookie was + acquired. If the server determines that the cookieverf is no longer + valid for the directory, the error NFS4ERR_NOT_SAME must be returned. + + The dircount portion of the argument is a hint of the maximum number + of bytes of directory information that should be returned. This + value represents the length of the names of the directory entries and + the cookie value for these entries. This length represents the XDR + encoding of the data (names and cookies) and not the length in the + native format of the server. + + The maxcount value of the argument is the maximum number of bytes for + the result. This maximum size represents all of the data being + returned within the READDIR4resok structure and includes the XDR + overhead. The server may return less data. If the server is unable + to return a single directory entry within the maxcount limit, the + error NFS4ERR_TOOSMALL will be returned to the client. + + Finally, attr_request represents the list of attributes to be + returned for each directory entry supplied by the server. + + On successful return, the server's response will provide a list of + directory entries. Each of these entries contains the name of the + directory entry, a cookie value for that entry, and the associated + attributes as requested. The "eof" flag has a value of TRUE if there + are no more entries in the directory. + + The cookie value is only meaningful to the server and is used as a + "bookmark" for the directory entry. As mentioned, this cookie is + used by the client for subsequent READDIR operations so that it may + continue reading a directory. The cookie is similar in concept to a + + + +Haynes & Noveck Standards Track [Page 270] + +RFC 7530 NFSv4 March 2015 + + + READ offset but should not be interpreted as such by the client. The + server SHOULD try to accept cookie values issued with READDIR + responses even if the directory has been modified between the READDIR + calls but MAY return NFS4ERR_NOT_VALID if this is not possible, as + might be the case if the server has rebooted in the interim. + + In some cases, the server may encounter an error while obtaining the + attributes for a directory entry. Instead of returning an error for + the entire READDIR operation, the server can instead return the + attribute 'fattr4_rdattr_error'. With this, the server is able to + communicate the failure to the client and not fail the entire + operation in the instance of what might be a transient failure. + Obviously, the client must request the fattr4_rdattr_error attribute + for this method to work properly. If the client does not request the + attribute, the server has no choice but to return failure for the + entire READDIR operation. + + For some file system environments, the directory entries "." and ".." + have special meaning, and in other environments, they may not. If + the server supports these special entries within a directory, they + should not be returned to the client as part of the READDIR response. + To enable some client environments, the cookie values of 0, 1, and 2 + are to be considered reserved. Note that the UNIX client will use + these values when combining the server's response and local + representations to enable a fully formed UNIX directory presentation + to the application. + + For READDIR arguments, cookie values of 1 and 2 SHOULD NOT be used, + and for READDIR results, cookie values of 0, 1, and 2 MUST NOT be + returned. + + On success, the current filehandle retains its value. + +16.24.5. IMPLEMENTATION + + The server's file system directory representations can differ + greatly. A client's programming interfaces may also be bound to the + local operating environment in a way that does not translate well + into the NFS protocol. Therefore, the dircount and maxcount fields + are provided to allow the client the ability to provide guidelines to + the server. If the client is aggressive about attribute collection + during a READDIR, the server has an idea of how to limit the encoded + response. The dircount field provides a hint on the number of + entries based solely on the names of the directory entries. Since it + is a hint, it may be possible that a dircount value is zero. In this + case, the server is free to ignore the dircount value and return + directory information based on the specified maxcount value. + + + + +Haynes & Noveck Standards Track [Page 271] + +RFC 7530 NFSv4 March 2015 + + + As there is no way for the client to indicate that a cookie value, + once received, will not be subsequently used, server implementations + should avoid schemes that allocate memory corresponding to a returned + cookie. Such allocation can be avoided if the server bases cookie + values on a value such as the offset within the directory where the + scan is to be resumed. + + Cookies generated by such techniques should be designed to remain + valid despite modification of the associated directory. If a server + were to invalidate a cookie because of a directory modification, + READDIRs of large directories might never finish. + + If a directory is deleted after the client has carried out one or + more READDIR operations on the directory, the cookies returned will + become invalid; however, the server does not need to be concerned, as + the directory filehandle used previously would have become stale and + would be reported as such on subsequent READDIR operations. The + server would not need to check the cookie verifier in this case. + + However, certain reorganization operations on a directory (including + directory compaction) may invalidate READDIR cookies previously given + out. When such a situation occurs, the server should modify the + cookie verifier so as to disallow the use of cookies that would + otherwise no longer be valid. + + The cookieverf may be used by the server to help manage cookie values + that may become stale. It should be a rare occurrence that a server + is unable to continue properly reading a directory with the provided + cookie/cookieverf pair. The server should make every effort to avoid + this condition since the application at the client may not be able to + properly handle this type of failure. + + The use of the cookieverf will also protect the client from using + READDIR cookie values that may be stale. For example, if the file + system has been migrated, the server may or may not be able to use + the same cookie values to service READDIR as the previous server + used. With the client providing the cookieverf, the server is able + to provide the appropriate response to the client. This prevents the + case where the server may accept a cookie value but the underlying + directory has changed and the response is invalid from the client's + context of its previous READDIR. + + Since some servers will not be returning "." and ".." entries as has + been done with previous versions of the NFS protocol, the client that + requires these entries be present in READDIR responses must fabricate + them. + + + + + +Haynes & Noveck Standards Track [Page 272] + +RFC 7530 NFSv4 March 2015 + + +16.25. Operation 27: READLINK - Read Symbolic Link + +16.25.1. SYNOPSIS + + (cfh) -> linktext + +16.25.2. ARGUMENT + + /* CURRENT_FH: symlink */ + void; + +16.25.3. RESULT + + struct READLINK4resok { + linktext4 link; + }; + + union READLINK4res switch (nfsstat4 status) { + case NFS4_OK: + READLINK4resok resok4; + default: + void; + }; + +16.25.4. DESCRIPTION + + READLINK reads the data associated with a symbolic link. The data is + a UTF-8 string that is opaque to the server. That is, whether + created by an NFS client or created locally on the server, the data + in a symbolic link is not interpreted when created but is simply + stored. + + On success, the current filehandle retains its value. + +16.25.5. IMPLEMENTATION + + A symbolic link is nominally a pointer to another file. The data is + not necessarily interpreted by the server; it is just stored in the + file. It is possible for a client implementation to store a pathname + that is not meaningful to the server operating system in a symbolic + link. A READLINK operation returns the data to the client for + interpretation. If different implementations want to share access to + symbolic links, then they must agree on the interpretation of the + data in the symbolic link. + + The READLINK operation is only allowed on objects of type NF4LNK. + The server should return the error NFS4ERR_INVAL if the object is not + of type NF4LNK. + + + +Haynes & Noveck Standards Track [Page 273] + +RFC 7530 NFSv4 March 2015 + + +16.26. Operation 28: REMOVE - Remove File System Object + +16.26.1. SYNOPSIS + + (cfh), filename -> change_info + +16.26.2. ARGUMENT + + struct REMOVE4args { + /* CURRENT_FH: directory */ + component4 target; + }; + +16.26.3. RESULT + + struct REMOVE4resok { + change_info4 cinfo; + }; + + union REMOVE4res switch (nfsstat4 status) { + case NFS4_OK: + REMOVE4resok resok4; + default: + void; + }; + +16.26.4. DESCRIPTION + + The REMOVE operation removes (deletes) a directory entry named by + filename from the directory corresponding to the current filehandle. + If the entry in the directory was the last reference to the + corresponding file system object, the object may be destroyed. + + For the directory where the filename was removed, the server returns + change_info4 information in cinfo. With the atomic field of the + change_info4 struct, the server will indicate if the before and after + change attributes were obtained atomically with respect to the + removal. + + If the target is of zero length, NFS4ERR_INVAL will be returned. The + target is also subject to the normal UTF-8, character support, and + name checks. See Section 12.7 for further discussion. + + On success, the current filehandle retains its value. + + + + + + + +Haynes & Noveck Standards Track [Page 274] + +RFC 7530 NFSv4 March 2015 + + +16.26.5. IMPLEMENTATION + + NFSv3 required a different operator -- RMDIR -- for directory + removal, and REMOVE for non-directory removal. This allowed clients + to skip checking the file type when being passed a non-directory + delete system call (e.g., unlink() [unlink] in POSIX) to remove a + directory, as well as the converse (e.g., a rmdir() on a + non-directory), because they knew the server would check the file + type. NFSv4 REMOVE can be used to delete any directory entry, + independent of its file type. The implementer of an NFSv4 client's + entry points from the unlink() and rmdir() system calls should first + check the file type against the types the system call is allowed to + remove before issuing a REMOVE. Alternatively, the implementer can + produce a COMPOUND call that includes a LOOKUP/VERIFY sequence to + verify the file type before a REMOVE operation in the same COMPOUND + call. + + The concept of last reference is server specific. However, if the + numlinks field in the previous attributes of the object had the value + 1, the client should not rely on referring to the object via a + filehandle. Likewise, the client should not rely on the resources + (disk space, directory entry, and so on) formerly associated with the + object becoming immediately available. Thus, if a client needs to be + able to continue to access a file after using REMOVE to remove it, + the client should take steps to make sure that the file will still be + accessible. The usual mechanism used is to RENAME the file from its + old name to a new hidden name. + + If the server finds that the file is still open when the REMOVE + arrives: + + o The server SHOULD NOT delete the file's directory entry if the + file was opened with OPEN4_SHARE_DENY_WRITE or + OPEN4_SHARE_DENY_BOTH. + + o If the file was not opened with OPEN4_SHARE_DENY_WRITE or + OPEN4_SHARE_DENY_BOTH, the server SHOULD delete the file's + directory entry. However, until the last CLOSE of the file, the + server MAY continue to allow access to the file via its + filehandle. + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 275] + +RFC 7530 NFSv4 March 2015 + + +16.27. Operation 29: RENAME - Rename Directory Entry + +16.27.1. SYNOPSIS + + (sfh), oldname, (cfh), newname -> source_cinfo, target_cinfo + +16.27.2. ARGUMENT + + struct RENAME4args { + /* SAVED_FH: source directory */ + component4 oldname; + /* CURRENT_FH: target directory */ + component4 newname; + }; + +16.27.3. RESULT + + struct RENAME4resok { + change_info4 source_cinfo; + change_info4 target_cinfo; + }; + + union RENAME4res switch (nfsstat4 status) { + case NFS4_OK: + RENAME4resok resok4; + default: + void; + }; + +16.27.4. DESCRIPTION + + The RENAME operation renames the object identified by oldname in the + source directory corresponding to the saved filehandle, as set by the + SAVEFH operation, to newname in the target directory corresponding to + the current filehandle. The operation is required to be atomic to + the client. Source and target directories must reside on the same + file system on the server. On success, the current filehandle will + continue to be the target directory. + + If the target directory already contains an entry with the name + newname, the source object must be compatible with the target: either + both are non-directories, or both are directories, and the target + must be empty. If compatible, the existing target is removed before + the rename occurs (see Section 16.26 for client and server actions + whenever a target is removed). If they are not compatible or if the + target is a directory but not empty, the server will return the error + NFS4ERR_EXIST. + + + + +Haynes & Noveck Standards Track [Page 276] + +RFC 7530 NFSv4 March 2015 + + + If oldname and newname both refer to the same file (they might be + hard links of each other), then RENAME should perform no action and + return success. + + For both directories involved in the RENAME, the server returns + change_info4 information. With the atomic field of the change_info4 + struct, the server will indicate if the before and after change + attributes were obtained atomically with respect to the rename. + + If the oldname refers to a named attribute and the saved and current + filehandles refer to the named attribute directories of different + file system objects, the server will return NFS4ERR_XDEV, just as if + the saved and current filehandles represented directories on + different file systems. + + If the oldname or newname is of zero length, NFS4ERR_INVAL will be + returned. The oldname and newname are also subject to the normal + UTF-8, character support, and name checks. See Section 12.7 for + further discussion. + +16.27.5. IMPLEMENTATION + + The RENAME operation must be atomic to the client. The statement + "source and target directories must reside on the same file system on + the server" means that the fsid fields in the attributes for the + directories are the same. If they reside on different file systems, + the error NFS4ERR_XDEV is returned. + + Based on the value of the fh_expire_type attribute for the object, + the filehandle may or may not expire on a RENAME. However, server + implementers are strongly encouraged to attempt to keep filehandles + from expiring in this fashion. + + On some servers, the filenames "." and ".." are illegal as either + oldname or newname and will result in the error NFS4ERR_BADNAME. In + addition, on many servers the case of oldname or newname being an + alias for the source directory will be checked for. Such servers + will return the error NFS4ERR_INVAL in these cases. + + If either of the source or target filehandles are not directories, + the server will return NFS4ERR_NOTDIR. + + + + + + + + + + +Haynes & Noveck Standards Track [Page 277] + +RFC 7530 NFSv4 March 2015 + + +16.28. Operation 30: RENEW - Renew a Lease + +16.28.1. SYNOPSIS + + clientid -> () + +16.28.2. ARGUMENT + + struct RENEW4args { + clientid4 clientid; + }; + +16.28.3. RESULT + + struct RENEW4res { + nfsstat4 status; + }; + +16.28.4. DESCRIPTION + + The RENEW operation is used by the client to renew leases that it + currently holds at a server. In processing the RENEW request, the + server renews all leases associated with the client. The associated + leases are determined by the clientid provided via the SETCLIENTID + operation. + +16.28.5. IMPLEMENTATION + + When the client holds delegations, it needs to use RENEW to detect + when the server has determined that the callback path is down. When + the server has made such a determination, only the RENEW operation + will renew the lease on delegations. If the server determines the + callback path is down, it returns NFS4ERR_CB_PATH_DOWN. Even though + it returns NFS4ERR_CB_PATH_DOWN, the server MUST renew the lease on + the byte-range locks and share reservations that the client has + established on the server. If for some reason the lock and share + reservation lease cannot be renewed, then the server MUST return an + error other than NFS4ERR_CB_PATH_DOWN, even if the callback path is + also down. In the event that the server has conditions such that it + could return either NFS4ERR_CB_PATH_DOWN or NFS4ERR_LEASE_MOVED, + NFS4ERR_LEASE_MOVED MUST be handled first. + + + + + + + + + + +Haynes & Noveck Standards Track [Page 278] + +RFC 7530 NFSv4 March 2015 + + + The client that issues RENEW MUST choose the principal, RPC security + flavor, and, if applicable, GSS-API mechanism and service via one of + the following algorithms: + + o The client uses the same principal, RPC security flavor, and -- if + the flavor was RPCSEC_GSS -- the same mechanism and service that + were used when the client ID was established via + SETCLIENTID_CONFIRM. + + o The client uses any principal, RPC security flavor, mechanism, and + service combination that currently has an OPEN file on the server. + That is, the same principal had a successful OPEN operation; the + file is still open by that principal; and the flavor, mechanism, + and service of RENEW match that of the previous OPEN. + + The server MUST reject a RENEW that does not use one of the + aforementioned algorithms, with the error NFS4ERR_ACCESS. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 279] + +RFC 7530 NFSv4 March 2015 + + +16.29. Operation 31: RESTOREFH - Restore Saved Filehandle + +16.29.1. SYNOPSIS + + (sfh) -> (cfh) + +16.29.2. ARGUMENT + + /* SAVED_FH: */ + void; + +16.29.3. RESULT + + struct RESTOREFH4res { + /* CURRENT_FH: value of saved fh */ + nfsstat4 status; + }; + +16.29.4. DESCRIPTION + + Set the current filehandle to the value in the saved filehandle. If + there is no saved filehandle, then return the error + NFS4ERR_RESTOREFH. + +16.29.5. IMPLEMENTATION + + Operations like OPEN and LOOKUP use the current filehandle to + represent a directory and replace it with a new filehandle. Assuming + that the previous filehandle was saved with a SAVEFH operator, the + previous filehandle can be restored as the current filehandle. This + is commonly used to obtain post-operation attributes for the + directory, e.g., + + PUTFH (directory filehandle) + SAVEFH + GETATTR attrbits (pre-op dir attrs) + CREATE optbits "foo" attrs + GETATTR attrbits (file attributes) + RESTOREFH + GETATTR attrbits (post-op dir attrs) + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 280] + +RFC 7530 NFSv4 March 2015 + + +16.30. Operation 32: SAVEFH - Save Current Filehandle + +16.30.1. SYNOPSIS + + (cfh) -> (sfh) + +16.30.2. ARGUMENT + + /* CURRENT_FH: */ + void; + +16.30.3. RESULT + + struct SAVEFH4res { + /* SAVED_FH: value of current fh */ + nfsstat4 status; + }; + +16.30.4. DESCRIPTION + + Save the current filehandle. If a previous filehandle was saved, + then it is no longer accessible. The saved filehandle can be + restored as the current filehandle with the RESTOREFH operator. + + On success, the current filehandle retains its value. + +16.30.5. IMPLEMENTATION + + + + + + + + + + + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 281] + +RFC 7530 NFSv4 March 2015 + + +16.31. Operation 33: SECINFO - Obtain Available Security + +16.31.1. SYNOPSIS + + (cfh), name -> { secinfo } + +16.31.2. ARGUMENT + + struct SECINFO4args { + /* CURRENT_FH: directory */ + component4 name; + }; + +16.31.3. RESULT + + /* + * From RFC 2203 + */ + enum rpc_gss_svc_t { + RPC_GSS_SVC_NONE = 1, + RPC_GSS_SVC_INTEGRITY = 2, + RPC_GSS_SVC_PRIVACY = 3 + }; + + struct rpcsec_gss_info { + sec_oid4 oid; + qop4 qop; + rpc_gss_svc_t service; + }; + + /* RPCSEC_GSS has a value of '6'. See RFC 2203 */ + union secinfo4 switch (uint32_t flavor) { + case RPCSEC_GSS: + rpcsec_gss_info flavor_info; + default: + void; + }; + + typedef secinfo4 SECINFO4resok<>; + + union SECINFO4res switch (nfsstat4 status) { + case NFS4_OK: + SECINFO4resok resok4; + default: + void; + }; + + + + + +Haynes & Noveck Standards Track [Page 282] + +RFC 7530 NFSv4 March 2015 + + +16.31.4. DESCRIPTION + + The SECINFO operation is used by the client to obtain a list of valid + RPC authentication flavors for a specific directory filehandle, + filename pair. SECINFO should apply the same access methodology used + for LOOKUP when evaluating the name. Therefore, if the requester + does not have the appropriate access to perform a LOOKUP for the + name, then SECINFO must behave the same way and return + NFS4ERR_ACCESS. + + The result will contain an array that represents the security + mechanisms available, with an order corresponding to the server's + preferences, the most preferred being first in the array. The client + is free to pick whatever security mechanism it both desires and + supports, or to pick -- in the server's preference order -- the first + one it supports. The array entries are represented by the secinfo4 + structure. The field 'flavor' will contain a value of AUTH_NONE, + AUTH_SYS (as defined in [RFC5531]), or RPCSEC_GSS (as defined in + [RFC2203]). + + For the flavors AUTH_NONE and AUTH_SYS, no additional security + information is returned. For a return value of RPCSEC_GSS, a + security triple is returned that contains the mechanism object id (as + defined in [RFC2743]), the quality of protection (as defined in + [RFC2743]), and the service type (as defined in [RFC2203]). It is + possible for SECINFO to return multiple entries with flavor equal to + RPCSEC_GSS, with different security triple values. + + On success, the current filehandle retains its value. + + If the name has a length of 0 (zero), or if the name does not obey + the UTF-8 definition, the error NFS4ERR_INVAL will be returned. + +16.31.5. IMPLEMENTATION + + The SECINFO operation is expected to be used by the NFS client when + the error value of NFS4ERR_WRONGSEC is returned from another NFS + operation. This signifies to the client that the server's security + policy is different from what the client is currently using. At this + point, the client is expected to obtain a list of possible security + flavors and choose what best suits its policies. + + As mentioned, the server's security policies will determine when a + client request receives NFS4ERR_WRONGSEC. The operations that may + receive this error are LINK, LOOKUP, LOOKUPP, OPEN, PUTFH, PUTPUBFH, + PUTROOTFH, RENAME, RESTOREFH, and, indirectly, READDIR. LINK and + RENAME will only receive this error if the security used for the + operation is inappropriate for the saved filehandle. With the + + + +Haynes & Noveck Standards Track [Page 283] + +RFC 7530 NFSv4 March 2015 + + + exception of READDIR, these operations represent the point at which + the client can instantiate a filehandle into the current filehandle + at the server. The filehandle is either provided by the client + (PUTFH, PUTPUBFH, PUTROOTFH) or generated as a result of a name-to- + filehandle translation (LOOKUP and OPEN). RESTOREFH is different + because the filehandle is a result of a previous SAVEFH. Even though + the filehandle, for RESTOREFH, might have previously passed the + server's inspection for a security match, the server will check it + again on RESTOREFH to ensure that the security policy has not + changed. + + If the client wants to resolve an error return of NFS4ERR_WRONGSEC, + the following will occur: + + o For LOOKUP and OPEN, the client will use SECINFO with the same + current filehandle and name as provided in the original LOOKUP or + OPEN to enumerate the available security triples. + + o For LINK, PUTFH, RENAME, and RESTOREFH, the client will use + SECINFO and provide the parent directory filehandle and the object + name that corresponds to the filehandle originally provided by the + PUTFH or RESTOREFH, or, for LINK and RENAME, the SAVEFH. + + o For LOOKUPP, PUTROOTFH, and PUTPUBFH, the client will be unable to + use the SECINFO operation since SECINFO requires a current + filehandle and none exist for these three operations. Therefore, + the client must iterate through the security triples available at + the client and re-attempt the PUTROOTFH or PUTPUBFH operation. In + the unfortunate event that none of the MANDATORY security triples + are supported by the client and server, the client SHOULD try + using others that support integrity. Failing that, the client can + try using AUTH_NONE, but because such forms lack integrity checks, + this puts the client at risk. Nonetheless, the server SHOULD + allow the client to use whatever security form the client requests + and the server supports, since the risks of doing so are on the + client. + + The READDIR operation will not directly return the NFS4ERR_WRONGSEC + error. However, if the READDIR request included a request for + attributes, it is possible that the READDIR request's security triple + does not match that of a directory entry. If this is the case and + the client has requested the rdattr_error attribute, the server will + return the NFS4ERR_WRONGSEC error in rdattr_error for the entry. + + + + + + + + +Haynes & Noveck Standards Track [Page 284] + +RFC 7530 NFSv4 March 2015 + + + Note that a server MAY use the AUTH_NONE flavor to signify that the + client is allowed to attempt to use authentication flavors that are + not explicitly listed in the SECINFO results. Instead of using a + listed flavor, the client might then, for instance, opt to use an + otherwise unlisted RPCSEC_GSS mechanism instead of AUTH_NONE. It may + wish to do so in order to meet an application requirement for data + integrity or privacy. In choosing to use an unlisted flavor, the + client SHOULD always be prepared to handle a failure by falling back + to using AUTH_NONE or another listed flavor. It cannot assume that + identity mapping is supported and should be prepared for the fact + that its identity is squashed. + + See Section 19 for a discussion on the recommendations for security + flavors used by SECINFO. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 285] + +RFC 7530 NFSv4 March 2015 + + +16.32. Operation 34: SETATTR - Set Attributes + +16.32.1. SYNOPSIS + + (cfh), stateid, attrmask, attr_vals -> attrsset + +16.32.2. ARGUMENT + + struct SETATTR4args { + /* CURRENT_FH: target object */ + stateid4 stateid; + fattr4 obj_attributes; + }; + +16.32.3. RESULT + + struct SETATTR4res { + nfsstat4 status; + bitmap4 attrsset; + }; + +16.32.4. DESCRIPTION + + The SETATTR operation changes one or more of the attributes of a file + system object. The new attributes are specified with a bitmap and + the attributes that follow the bitmap in bit order. + + The stateid argument for SETATTR is used to provide byte-range + locking context that is necessary for SETATTR requests that set the + size attribute. Since setting the size attribute modifies the file's + data, it has the same locking requirements as a corresponding WRITE. + Any SETATTR that sets the size attribute is incompatible with a share + reservation that specifies OPEN4_SHARE_DENY_WRITE. The area between + the old end-of-file and the new end-of-file is considered to be + modified just as would have been the case had the area in question + been specified as the target of WRITE, for the purpose of checking + conflicts with byte-range locks, for those cases in which a server is + implementing mandatory byte-range locking behavior. A valid stateid + SHOULD always be specified. When the file size attribute is not set, + the special anonymous stateid MAY be passed. + + On either success or failure of the operation, the server will return + the attrsset bitmask to represent what (if any) attributes were + successfully set. The attrsset in the response is a subset of the + bitmap4 that is part of the obj_attributes in the argument. + + On success, the current filehandle retains its value. + + + + +Haynes & Noveck Standards Track [Page 286] + +RFC 7530 NFSv4 March 2015 + + +16.32.5. IMPLEMENTATION + + If the request specifies the owner attribute to be set, the server + SHOULD allow the operation to succeed if the current owner of the + object matches the value specified in the request. Some servers may + be implemented in such a way as to prohibit the setting of the owner + attribute unless the requester has the privilege to do so. If the + server is lenient in this one case of matching owner values, the + client implementation may be simplified in cases of creation of an + object (e.g., an exclusive create via OPEN) followed by a SETATTR. + + The file size attribute is used to request changes to the size of a + file. A value of zero causes the file to be truncated, a value less + than the current size of the file causes data from the new size to + the end of the file to be discarded, and a size greater than the + current size of the file causes logically zeroed data bytes to be + added to the end of the file. Servers are free to implement this + using holes or actual zero data bytes. Clients should not make any + assumptions regarding a server's implementation of this feature, + beyond that the bytes returned will be zeroed. Servers MUST support + extending the file size via SETATTR. + + SETATTR is not guaranteed atomic. A failed SETATTR may partially + change a file's attributes -- hence, the reason why the reply always + includes the status and the list of attributes that were set. + + If the object whose attributes are being changed has a file + delegation that is held by a client other than the one doing the + SETATTR, the delegation(s) must be recalled, and the operation cannot + proceed to actually change an attribute until each such delegation is + returned or revoked. In all cases in which delegations are recalled, + the server is likely to return one or more NFS4ERR_DELAY errors while + the delegation(s) remains outstanding, although it might not do that + if the delegations are returned quickly. + + Changing the size of a file with SETATTR indirectly changes the + time_modify and change attributes. A client must account for this, + as size changes can result in data deletion. + + The attributes time_access_set and time_modify_set are write-only + attributes constructed as a switched union so the client can direct + the server in setting the time values. If the switched union + specifies SET_TO_CLIENT_TIME4, the client has provided an nfstime4 to + be used for the operation. If the switch union does not specify + SET_TO_CLIENT_TIME4, the server is to use its current time for the + SETATTR operation. + + + + + +Haynes & Noveck Standards Track [Page 287] + +RFC 7530 NFSv4 March 2015 + + + If server and client times differ, programs that compare client times + to file times can break. A time maintenance protocol should be used + to limit client/server time skew. + + Use of a COMPOUND containing a VERIFY operation specifying only the + change attribute, immediately followed by a SETATTR, provides a means + whereby a client may specify a request that emulates the + functionality of the SETATTR guard mechanism of NFSv3. Since the + function of the guard mechanism is to avoid changes to the file + attributes based on stale information, delays between checking of the + guard condition and the setting of the attributes have the potential + to compromise this function, as would the corresponding delay in the + NFSv4 emulation. Therefore, NFSv4 servers should take care to avoid + such delays, to the degree possible, when executing such a request. + + If the server does not support an attribute as requested by the + client, the server should return NFS4ERR_ATTRNOTSUPP. + + A mask of the attributes actually set is returned by SETATTR in all + cases. That mask MUST NOT include attribute bits not requested to be + set by the client. If the attribute masks in the request and reply + are equal, the status field in the reply MUST be NFS4_OK. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 288] + +RFC 7530 NFSv4 March 2015 + + +16.33. Operation 35: SETCLIENTID - Negotiate Client ID + +16.33.1. SYNOPSIS + + client, callback, callback_ident -> clientid, setclientid_confirm + +16.33.2. ARGUMENT + + struct SETCLIENTID4args { + nfs_client_id4 client; + cb_client4 callback; + uint32_t callback_ident; + }; + +16.33.3. RESULT + + struct SETCLIENTID4resok { + clientid4 clientid; + verifier4 setclientid_confirm; + }; + + union SETCLIENTID4res switch (nfsstat4 status) { + case NFS4_OK: + SETCLIENTID4resok resok4; + case NFS4ERR_CLID_INUSE: + clientaddr4 client_using; + default: + void; + }; + +16.33.4. DESCRIPTION + + The client uses the SETCLIENTID operation to notify the server of its + intention to use a particular client identifier, callback, and + callback_ident for subsequent requests that entail creating lock, + share reservation, and delegation state on the server. Upon + successful completion the server will return a shorthand client ID + that, if confirmed via a separate step, will be used in subsequent + file locking and file open requests. Confirmation of the client ID + must be done via the SETCLIENTID_CONFIRM operation to return the + client ID and setclientid_confirm values, as verifiers, to the + server. Two verifiers are necessary because it is possible to use + SETCLIENTID and SETCLIENTID_CONFIRM to modify the callback and + callback_ident information but not the shorthand client ID. In that + event, the setclientid_confirm value is effectively the only + verifier. + + + + + +Haynes & Noveck Standards Track [Page 289] + +RFC 7530 NFSv4 March 2015 + + + The callback information provided in this operation will be used if + the client is provided an open delegation at a future point. + Therefore, the client must correctly reflect the program and port + numbers for the callback program at the time SETCLIENTID is used. + + The callback_ident value is used by the server on the callback. The + client can leverage the callback_ident to eliminate the need for more + than one callback RPC program number, while still being able to + determine which server is initiating the callback. + +16.33.5. IMPLEMENTATION + + To understand how to implement SETCLIENTID, make the following + notations. Let: + + x be the value of the client.id subfield of the SETCLIENTID4args + structure. + + v be the value of the client.verifier subfield of the + SETCLIENTID4args structure. + + c be the value of the client ID field returned in the + SETCLIENTID4resok structure. + + k represent the value combination of the callback and callback_ident + fields of the SETCLIENTID4args structure. + + s be the setclientid_confirm value returned in the SETCLIENTID4resok + structure. + + { v, x, c, k, s } be a quintuple for a client record. A client + record is confirmed if there has been a SETCLIENTID_CONFIRM + operation to confirm it. Otherwise, it is unconfirmed. An + unconfirmed record is established by a SETCLIENTID call. + + Since SETCLIENTID is a non-idempotent operation, let us assume that + the server is implementing the duplicate request cache (DRC). + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 290] + +RFC 7530 NFSv4 March 2015 + + + When the server gets a SETCLIENTID { v, x, k } request, it processes + it in the following manner. + + o It first looks up the request in the DRC. If there is a hit, it + returns the result cached in the DRC. The server does NOT remove + client state (locks, shares, delegations), nor does it modify any + recorded callback and callback_ident information for client { x }. + + For any DRC miss, the server takes the client ID string x, and + searches for client records for x that the server may have + recorded from previous SETCLIENTID calls. For any confirmed + record with the same id string x, if the recorded principal does + not match that of the SETCLIENTID call, then the server returns an + NFS4ERR_CLID_INUSE error. + + For brevity of discussion, the remaining description of the + processing assumes that there was a DRC miss, and that where the + server has previously recorded a confirmed record for client x, + the aforementioned principal check has successfully passed. + + o The server checks if it has recorded a confirmed record for { v, + x, c, l, s }, where l may or may not equal k. If so, and since + the id verifier v of the request matches that which is confirmed + and recorded, the server treats this as a probable callback + information update and records an unconfirmed { v, x, c, k, t } + and leaves the confirmed { v, x, c, l, s } in place, such that + t != s. It does not matter whether k equals l or not. Any + pre-existing unconfirmed { v, x, c, *, * } is removed. + + The server returns { c, t }. It is indeed returning the old + clientid4 value c, because the client apparently only wants to + update callback value k to value l. It's possible this request is + one from the Byzantine router that has stale callback information, + but this is not a problem. The callback information update is + only confirmed if followed up by a SETCLIENTID_CONFIRM { c, t }. + + The server awaits confirmation of k via SETCLIENTID_CONFIRM + { c, t }. + + The server does NOT remove client (lock/share/delegation) state + for x. + + + + + + + + + + +Haynes & Noveck Standards Track [Page 291] + +RFC 7530 NFSv4 March 2015 + + + o The server has previously recorded a confirmed { u, x, c, l, s } + record such that v != u, l may or may not equal k, and has not + recorded any unconfirmed { *, x, *, *, * } record for x. The + server records an unconfirmed { v, x, d, k, t } (d != c, t != s). + + The server returns { d, t }. + + The server awaits confirmation of { d, k } via SETCLIENTID_CONFIRM + { d, t }. + + The server does NOT remove client (lock/share/delegation) state + for x. + + o The server has previously recorded a confirmed { u, x, c, l, s } + record such that v != u, l may or may not equal k, and recorded an + unconfirmed { w, x, d, m, t } record such that c != d, t != s, m + may or may not equal k, m may or may not equal l, and k may or may + not equal l. Whether w == v or w != v makes no difference. The + server simply removes the unconfirmed { w, x, d, m, t } record and + replaces it with an unconfirmed { v, x, e, k, r } record, such + that e != d, e != c, r != t, r != s. + + The server returns { e, r }. + + The server awaits confirmation of { e, k } via SETCLIENTID_CONFIRM + { e, r }. + + The server does NOT remove client (lock/share/delegation) state + for x. + + o The server has no confirmed { *, x, *, *, * } for x. It may or + may not have recorded an unconfirmed { u, x, c, l, s }, where l + may or may not equal k, and u may or may not equal v. Any + unconfirmed record { u, x, c, l, * }, regardless of whether u == v + or l == k, is replaced with an unconfirmed record { v, x, d, k, t + } where d != c, t != s. + + The server returns { d, t }. + + The server awaits confirmation of { d, k } via SETCLIENTID_CONFIRM + { d, t }. The server does NOT remove client (lock/share/ + delegation) state for x. + + The server generates the clientid and setclientid_confirm values and + must take care to ensure that these values are extremely unlikely to + ever be regenerated. + + + + + +Haynes & Noveck Standards Track [Page 292] + +RFC 7530 NFSv4 March 2015 + + +16.34. Operation 36: SETCLIENTID_CONFIRM - Confirm Client ID + +16.34.1. SYNOPSIS + + clientid, setclientid_confirm -> - + +16.34.2. ARGUMENT + + struct SETCLIENTID_CONFIRM4args { + clientid4 clientid; + verifier4 setclientid_confirm; + }; + +16.34.3. RESULT + + struct SETCLIENTID_CONFIRM4res { + nfsstat4 status; + }; + +16.34.4. DESCRIPTION + + This operation is used by the client to confirm the results from a + previous call to SETCLIENTID. The client provides the server- + supplied (from a SETCLIENTID response) client ID. The server + responds with a simple status of success or failure. + +16.34.5. IMPLEMENTATION + + The client must use the SETCLIENTID_CONFIRM operation to confirm the + following two distinct cases: + + o The client's use of a new shorthand client identifier (as returned + from the server in the response to SETCLIENTID), a new callback + value (as specified in the arguments to SETCLIENTID), and a new + callback_ident value (as specified in the arguments to + SETCLIENTID). The client's use of SETCLIENTID_CONFIRM in this + case also confirms the removal of any of the client's previous + relevant leased state. Relevant leased client state includes + byte-range locks, share reservations, and -- where the server does + not support the CLAIM_DELEGATE_PREV claim type -- delegations. If + the server supports CLAIM_DELEGATE_PREV, then SETCLIENTID_CONFIRM + MUST NOT remove delegations for this client; relevant leased + client state would then just include byte-range locks and share + reservations. + + + + + + + +Haynes & Noveck Standards Track [Page 293] + +RFC 7530 NFSv4 March 2015 + + + o The client's reuse of an old, previously confirmed shorthand + client identifier; a new callback value; and a new callback_ident + value. The client's use of SETCLIENTID_CONFIRM in this case MUST + NOT result in the removal of any previous leased state (locks, + share reservations, and delegations). + + We use the same notation and definitions for v, x, c, k, s, and + unconfirmed and confirmed client records as introduced in the + description of the SETCLIENTID operation. The arguments to + SETCLIENTID_CONFIRM are indicated by the notation { c, s }, where c + is a value of type clientid4, and s is a value of type verifier4 + corresponding to the setclientid_confirm field. + + As with SETCLIENTID, SETCLIENTID_CONFIRM is a non-idempotent + operation, and we assume that the server is implementing the + duplicate request cache (DRC). + + When the server gets a SETCLIENTID_CONFIRM { c, s } request, it + processes it in the following manner. + + o It first looks up the request in the DRC. If there is a hit, it + returns the result cached in the DRC. The server does not remove + any relevant leased client state, nor does it modify any recorded + callback and callback_ident information for client { x } as + represented by the shorthand value c. + + For a DRC miss, the server checks for client records that match the + shorthand value c. The processing cases are as follows: + + o The server has recorded an unconfirmed { v, x, c, k, s } record + and a confirmed { v, x, c, l, t } record, such that s != t. If + the principals of the records do not match that of the + SETCLIENTID_CONFIRM, the server returns NFS4ERR_CLID_INUSE, and no + relevant leased client state is removed and no recorded callback + and callback_ident information for client { x } is changed. + Otherwise, the confirmed { v, x, c, l, t } record is removed and + the unconfirmed { v, x, c, k, s } is marked as confirmed, thereby + modifying recorded and confirmed callback and callback_ident + information for client { x }. + + The server does not remove any relevant leased client state. + + The server returns NFS4_OK. + + + + + + + + +Haynes & Noveck Standards Track [Page 294] + +RFC 7530 NFSv4 March 2015 + + + o The server has not recorded an unconfirmed { v, x, c, *, * } and + has recorded a confirmed { v, x, c, *, s }. If the principals of + the record and of SETCLIENTID_CONFIRM do not match, the server + returns NFS4ERR_CLID_INUSE without removing any relevant leased + client state, and without changing recorded callback and + callback_ident values for client { x }. + + If the principals match, then what has likely happened is that the + client never got the response from the SETCLIENTID_CONFIRM, and + the DRC entry has been purged. Whatever the scenario, since the + principals match, as well as { c, s } matching a confirmed record, + the server leaves client x's relevant leased client state intact, + leaves its callback and callback_ident values unmodified, and + returns NFS4_OK. + + o The server has not recorded a confirmed { *, *, c, *, * } and has + recorded an unconfirmed { *, x, c, k, s }. Even if this is a + retry from the client, nonetheless the client's first + SETCLIENTID_CONFIRM attempt was not received by the server. Retry + or not, the server doesn't know, but it processes it as if it were + a first try. If the principal of the unconfirmed { *, x, c, k, s + } record mismatches that of the SETCLIENTID_CONFIRM request, the + server returns NFS4ERR_CLID_INUSE without removing any relevant + leased client state. + + Otherwise, the server records a confirmed { *, x, c, k, s }. If + there is also a confirmed { *, x, d, *, t }, the server MUST + remove client x's relevant leased client state and overwrite the + callback state with k. The confirmed record { *, x, d, *, t } is + removed. + + The server returns NFS4_OK. + + o The server has no record of a confirmed or unconfirmed { *, *, c, + *, s }. The server returns NFS4ERR_STALE_CLIENTID. The server + does not remove any relevant leased client state, nor does it + modify any recorded callback and callback_ident information for + any client. + + The server needs to cache unconfirmed { v, x, c, k, s } client + records and await for some time their confirmation. As should be + clear from the discussions of record processing for SETCLIENTID and + SETCLIENTID_CONFIRM, there are cases where the server does not + deterministically remove unconfirmed client records. To avoid + running out of resources, the server is not required to hold + unconfirmed records indefinitely. One strategy the server might use + is to set a limit on how many unconfirmed client records it will + maintain and then, when the limit would be exceeded, remove the + + + +Haynes & Noveck Standards Track [Page 295] + +RFC 7530 NFSv4 March 2015 + + + oldest record. Another strategy might be to remove an unconfirmed + record when some amount of time has elapsed. The choice of the + amount of time is fairly arbitrary, but it is surely no higher than + the server's lease time period. Consider that leases need to be + renewed before the lease time expires via an operation from the + client. If the client cannot issue a SETCLIENTID_CONFIRM after a + SETCLIENTID before a period of time equal to a lease expiration time, + then the client is unlikely to be able to maintain state on the + server during steady-state operation. + + If the client does send a SETCLIENTID_CONFIRM for an unconfirmed + record that the server has already deleted, the client will get + NFS4ERR_STALE_CLIENTID back. If so, the client should then start + over, and send SETCLIENTID to re-establish an unconfirmed client + record and get back an unconfirmed client ID and setclientid_confirm + verifier. The client should then send the SETCLIENTID_CONFIRM to + confirm the client ID. + + SETCLIENTID_CONFIRM does not establish or renew a lease. However, if + SETCLIENTID_CONFIRM removes relevant leased client state, and that + state does not include existing delegations, the server MUST allow + the client a period of time no less than the value of the lease_time + attribute, to reclaim (via the CLAIM_DELEGATE_PREV claim type of the + OPEN operation) its delegations before removing unreclaimed + delegations. + + + + + + + + + + + + + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 296] + +RFC 7530 NFSv4 March 2015 + + +16.35. Operation 37: VERIFY - Verify Same Attributes + +16.35.1. SYNOPSIS + + (cfh), fattr -> - + +16.35.2. ARGUMENT + + struct VERIFY4args { + /* CURRENT_FH: object */ + fattr4 obj_attributes; + }; + +16.35.3. RESULT + + struct VERIFY4res { + nfsstat4 status; + }; + +16.35.4. DESCRIPTION + + The VERIFY operation is used to verify that attributes have a value + assumed by the client before proceeding with subsequent operations in + the COMPOUND request. If any of the attributes do not match, then + the error NFS4ERR_NOT_SAME must be returned. The current filehandle + retains its value after successful completion of the operation. + +16.35.5. IMPLEMENTATION + + One possible use of the VERIFY operation is the following COMPOUND + sequence. With this, the client is attempting to verify that the + file being removed will match what the client expects to be removed. + This sequence can help prevent the unintended deletion of a file. + + PUTFH (directory filehandle) + LOOKUP (filename) + VERIFY (filehandle == fh) + PUTFH (directory filehandle) + REMOVE (filename) + + This sequence does not prevent a second client from removing and + creating a new file in the middle of this sequence, but it does help + avoid the unintended result. + + + + + + + + +Haynes & Noveck Standards Track [Page 297] + +RFC 7530 NFSv4 March 2015 + + + In the case that a RECOMMENDED attribute is specified in the VERIFY + operation and the server does not support that attribute for the file + system object, the error NFS4ERR_ATTRNOTSUPP is returned to the + client. + + When the attribute rdattr_error or any write-only attribute (e.g., + time_modify_set) is specified, the error NFS4ERR_INVAL is returned to + the client. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 298] + +RFC 7530 NFSv4 March 2015 + + +16.36. Operation 38: WRITE - Write to File + +16.36.1. SYNOPSIS + + (cfh), stateid, offset, stable, data -> count, committed, writeverf + +16.36.2. ARGUMENT + + enum stable_how4 { + UNSTABLE4 = 0, + DATA_SYNC4 = 1, + FILE_SYNC4 = 2 + }; + + struct WRITE4args { + /* CURRENT_FH: file */ + stateid4 stateid; + offset4 offset; + stable_how4 stable; + opaque data<>; + }; + +16.36.3. RESULT + + struct WRITE4resok { + count4 count; + stable_how4 committed; + verifier4 writeverf; + }; + + union WRITE4res switch (nfsstat4 status) { + case NFS4_OK: + WRITE4resok resok4; + default: + void; + }; + +16.36.4. DESCRIPTION + + The WRITE operation is used to write data to a regular file. The + target file is specified by the current filehandle. The offset + specifies the offset where the data should be written. An offset of + 0 (zero) specifies that the write should start at the beginning of + the file. The count, as encoded as part of the opaque data + parameter, represents the number of bytes of data that are to be + written. If the count is 0 (zero), the WRITE will succeed and return + a count of 0 (zero) subject to permissions checking. The server may + choose to write fewer bytes than requested by the client. + + + +Haynes & Noveck Standards Track [Page 299] + +RFC 7530 NFSv4 March 2015 + + + Part of the WRITE request is a specification of how the WRITE is to + be performed. The client specifies with the stable parameter the + method of how the data is to be processed by the server. If stable + is FILE_SYNC4, the server must commit the data written plus all file + system metadata to stable storage before returning results. This + corresponds to the NFSv2 protocol semantics. Any other behavior + constitutes a protocol violation. If stable is DATA_SYNC4, then the + server must commit all of the data to stable storage and enough of + the metadata to retrieve the data before returning. The server + implementer is free to implement DATA_SYNC4 in the same fashion as + FILE_SYNC4, but with a possible performance drop. If stable is + UNSTABLE4, the server is free to commit any part of the data and the + metadata to stable storage, including all or none, before returning a + reply to the client. There is no guarantee whether or when any + uncommitted data will subsequently be committed to stable storage. + The only guarantees made by the server are that it will not destroy + any data without changing the value of verf and that it will not + commit the data and metadata at a level less than that requested by + the client. + + The stateid value for a WRITE request represents a value returned + from a previous byte-range lock or share reservation request or the + stateid associated with a delegation. The stateid is used by the + server to verify that the associated share reservation and any + byte-range locks are still valid and to update lease timeouts for the + client. + + Upon successful completion, the following results are returned. The + count result is the number of bytes of data written to the file. The + server may write fewer bytes than requested. If so, the actual + number of bytes written starting at location, offset, is returned. + + The server also returns an indication of the level of commitment of + the data and metadata via committed. If the server committed all + data and metadata to stable storage, committed should be set to + FILE_SYNC4. If the level of commitment was at least as strong as + DATA_SYNC4, then committed should be set to DATA_SYNC4. Otherwise, + committed must be returned as UNSTABLE4. If stable was FILE4_SYNC, + then committed must also be FILE_SYNC4: anything else constitutes a + protocol violation. If stable was DATA_SYNC4, then committed may be + FILE_SYNC4 or DATA_SYNC4: anything else constitutes a protocol + violation. If stable was UNSTABLE4, then committed may be either + FILE_SYNC4, DATA_SYNC4, or UNSTABLE4. + + + + + + + + +Haynes & Noveck Standards Track [Page 300] + +RFC 7530 NFSv4 March 2015 + + + The final portion of the result is the write verifier. The write + verifier is a cookie that the client can use to determine whether the + server has changed instance (boot) state between a call to WRITE and + a subsequent call to either WRITE or COMMIT. This cookie must be + consistent during a single instance of the NFSv4 protocol service and + must be unique between instances of the NFSv4 protocol server, where + uncommitted data may be lost. + + If a client writes data to the server with the stable argument set to + UNSTABLE4 and the reply yields a committed response of DATA_SYNC4 or + UNSTABLE4, the client will follow up at some time in the future with + a COMMIT operation to synchronize outstanding asynchronous data and + metadata with the server's stable storage, barring client error. It + is possible that due to client crash or other error a subsequent + COMMIT will not be received by the server. + + For a WRITE using the special anonymous stateid, the server MAY allow + the WRITE to be serviced subject to mandatory file locks or the + current share deny modes for the file. For a WRITE using the special + READ bypass stateid, the server MUST NOT allow the WRITE operation to + bypass locking checks at the server, and the WRITE is treated exactly + the same as if the anonymous stateid were used. + + On success, the current filehandle retains its value. + +16.36.5. IMPLEMENTATION + + It is possible for the server to write fewer bytes of data than + requested by the client. In this case, the server should not return + an error unless no data was written at all. If the server writes + less than the number of bytes specified, the client should issue + another WRITE to write the remaining data. + + It is assumed that the act of writing data to a file will cause the + time_modify attribute of the file to be updated. However, the + time_modify attribute of the file should not be changed unless the + contents of the file are changed. Thus, a WRITE request with count + set to 0 should not cause the time_modify attribute of the file to be + updated. + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 301] + +RFC 7530 NFSv4 March 2015 + + + The definition of stable storage has been historically a point of + contention. The following expected properties of stable storage may + help in resolving design issues in the implementation. Stable + storage is persistent storage that survives: + + 1. Repeated power failures. + + 2. Hardware failures (of any board, power supply, etc.). + + 3. Repeated software crashes, including reboot cycle. + + This definition does not address failure of the stable storage module + itself. + + The verifier is defined to allow a client to detect different + instances of an NFSv4 protocol server over which cached, uncommitted + data may be lost. In the most likely case, the verifier allows the + client to detect server reboots. This information is required so + that the client can safely determine whether the server could have + lost cached data. If the server fails unexpectedly and the client + has uncommitted data from previous WRITE requests (done with the + stable argument set to UNSTABLE4 and in which the result committed + was returned as UNSTABLE4 as well), it may not have flushed cached + data to stable storage. The burden of recovery is on the client, and + the client will need to retransmit the data to the server. + + One suggested way to use the verifier would be to use the time that + the server was booted or the time the server was last started (if + restarting the server without a reboot results in lost buffers). + + The committed field in the results allows the client to do more + effective caching. If the server is committing all WRITE requests to + stable storage, then it should return with committed set to + FILE_SYNC4, regardless of the value of the stable field in the + arguments. A server that uses an NVRAM accelerator may choose to + implement this policy. The client can use this to increase the + effectiveness of the cache by discarding cached data that has already + been committed on the server. + + Some implementations may return NFS4ERR_NOSPC instead of + NFS4ERR_DQUOT when a user's quota is exceeded. In the case that the + current filehandle is a directory, the server will return + NFS4ERR_ISDIR. If the current filehandle is not a regular file or a + directory, the server will return NFS4ERR_INVAL. + + + + + + + +Haynes & Noveck Standards Track [Page 302] + +RFC 7530 NFSv4 March 2015 + + + If mandatory file locking is on for the file, and a corresponding + record of the data to be written to file is read or write locked by + an owner that is not associated with the stateid, the server will + return NFS4ERR_LOCKED. If so, the client must check if the owner + corresponding to the stateid used with the WRITE operation has a + conflicting read lock that overlaps with the region that was to be + written. If the stateid's owner has no conflicting read lock, then + the client should try to get the appropriate write byte-range lock + via the LOCK operation before re-attempting the WRITE. When the + WRITE completes, the client should release the byte-range lock via + LOCKU. + + If the stateid's owner had a conflicting read lock, then the client + has no choice but to return an error to the application that + attempted the WRITE. The reason is that since the stateid's owner + had a read lock, the server either (1) attempted to temporarily + effectively upgrade this read lock to a write lock or (2) has no + upgrade capability. If the server attempted to upgrade the read lock + and failed, it is pointless for the client to re-attempt the upgrade + via the LOCK operation, because there might be another client also + trying to upgrade. If two clients are blocked trying to upgrade the + same lock, the clients deadlock. If the server has no upgrade + capability, then it is pointless to try a LOCK operation to upgrade. + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 303] + +RFC 7530 NFSv4 March 2015 + + +16.37. Operation 39: RELEASE_LOCKOWNER - Release Lock-Owner State + +16.37.1. SYNOPSIS + + lock-owner -> () + +16.37.2. ARGUMENT + + struct RELEASE_LOCKOWNER4args { + lock_owner4 lock_owner; + }; + +16.37.3. RESULT + + struct RELEASE_LOCKOWNER4res { + nfsstat4 status; + }; + +16.37.4. DESCRIPTION + + This operation is used to notify the server that the lock_owner is no + longer in use by the client and that future client requests will not + reference this lock_owner. This allows the server to release cached + state related to the specified lock_owner. If file locks associated + with the lock_owner are held at the server, the error + NFS4ERR_LOCKS_HELD will be returned and no further action will be + taken. + +16.37.5. IMPLEMENTATION + + The client may choose to use this operation to ease the amount of + server state that is held. Information that can be released when a + RELEASE_LOCKOWNER is done includes the specified lock-owner string, + the seqid associated with the lock-owner, any saved reply for the + lock-owner, and any lock stateids associated with that lock-owner. + + Depending on the behavior of applications at the client, it may be + important for the client to use this operation since the server + has certain obligations with respect to holding a reference to + lock-owner-associated state as long as an associated file is open. + Therefore, if the client knows for certain that the lock_owner will + no longer be used to either reference existing lock stateids + associated with the lock-owner or create new ones, it should use + RELEASE_LOCKOWNER. + + + + + + + +Haynes & Noveck Standards Track [Page 304] + +RFC 7530 NFSv4 March 2015 + + +16.38. Operation 10044: ILLEGAL - Illegal Operation + +16.38.1. SYNOPSIS + + -> () + +16.38.2. ARGUMENT + + void; + +16.38.3. RESULT + + struct ILLEGAL4res { + nfsstat4 status; + }; + +16.38.4. DESCRIPTION + + This operation is a placeholder for encoding a result to handle the + case of the client sending an operation code within COMPOUND that is + not supported. See Section 15.2.4 for more details. + + The status field of ILLEGAL4res MUST be set to NFS4ERR_OP_ILLEGAL. + +16.38.5. IMPLEMENTATION + + A client will probably not send an operation with code OP_ILLEGAL, + but if it does, the response will be ILLEGAL4res, just as it would be + with any other invalid operation code. Note that if the server gets + an illegal operation code that is not OP_ILLEGAL, and if the server + checks for legal operation codes during the XDR decode phase, then + the ILLEGAL4res would not be returned. + + + + + + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 305] + +RFC 7530 NFSv4 March 2015 + + +17. NFSv4 Callback Procedures + + The procedures used for callbacks are defined in the following + sections. In the interest of clarity, the terms "client" and + "server" refer to NFS clients and servers, despite the fact that for + an individual callback RPC, the sense of these terms would be + precisely the opposite. + +17.1. Procedure 0: CB_NULL - No Operation + +17.1.1. SYNOPSIS + + + +17.1.2. ARGUMENT + + void; + +17.1.3. RESULT + + void; + +17.1.4. DESCRIPTION + + Standard NULL procedure. Void argument, void response. Even though + there is no direct functionality associated with this procedure, the + server will use CB_NULL to confirm the existence of a path for RPCs + from server to client. + + + + + + + + + + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 306] + +RFC 7530 NFSv4 March 2015 + + +17.2. Procedure 1: CB_COMPOUND - COMPOUND Operations + +17.2.1. SYNOPSIS + + compoundargs -> compoundres + +17.2.2. ARGUMENT + + enum nfs_cb_opnum4 { + OP_CB_GETATTR = 3, + OP_CB_RECALL = 4, + OP_CB_ILLEGAL = 10044 + }; + + union nfs_cb_argop4 switch (unsigned argop) { + case OP_CB_GETATTR: + CB_GETATTR4args opcbgetattr; + case OP_CB_RECALL: + CB_RECALL4args opcbrecall; + case OP_CB_ILLEGAL: void; + }; + + struct CB_COMPOUND4args { + utf8str_cs tag; + uint32_t minorversion; + uint32_t callback_ident; + nfs_cb_argop4 argarray<>; + }; + +17.2.3. RESULT + + union nfs_cb_resop4 switch (unsigned resop) { + case OP_CB_GETATTR: CB_GETATTR4res opcbgetattr; + case OP_CB_RECALL: CB_RECALL4res opcbrecall; + case OP_CB_ILLEGAL: CB_ILLEGAL4res opcbillegal; + }; + + struct CB_COMPOUND4res { + nfsstat4 status; + utf8str_cs tag; + nfs_cb_resop4 resarray<>; + }; + + + + + + + + + +Haynes & Noveck Standards Track [Page 307] + +RFC 7530 NFSv4 March 2015 + + +17.2.4. DESCRIPTION + + The CB_COMPOUND procedure is used to combine one or more of the + callback procedures into a single RPC request. The main callback RPC + program has two main procedures: CB_NULL and CB_COMPOUND. All other + operations use the CB_COMPOUND procedure as a wrapper. + + In the processing of the CB_COMPOUND procedure, the client may find + that it does not have the available resources to execute any or all + of the operations within the CB_COMPOUND sequence. In this case, the + error NFS4ERR_RESOURCE will be returned for the particular operation + within the CB_COMPOUND procedure where the resource exhaustion + occurred. This assumes that all previous operations within the + CB_COMPOUND sequence have been evaluated successfully. + + Contained within the CB_COMPOUND results is a status field. This + status must be equivalent to the status of the last operation that + was executed within the CB_COMPOUND procedure. Therefore, if an + operation incurred an error, then the status value will be the same + error value as is being returned for the operation that failed. + + For the definition of the tag field, see Section 15.2. + + The value of callback_ident is supplied by the client during + SETCLIENTID. The server must use the client-supplied callback_ident + during the CB_COMPOUND to allow the client to properly identify the + server. + + Illegal operation codes are handled in the same way as they are + handled for the COMPOUND procedure. + +17.2.5. IMPLEMENTATION + + The CB_COMPOUND procedure is used to combine individual operations + into a single RPC request. The client interprets each of the + operations in turn. If an operation is executed by the client and + the status of that operation is NFS4_OK, then the next operation in + the CB_COMPOUND procedure is executed. The client continues this + process until there are no more operations to be executed or one of + the operations has a status value other than NFS4_OK. + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 308] + +RFC 7530 NFSv4 March 2015 + + +18. NFSv4 Callback Operations + +18.1. Operation 3: CB_GETATTR - Get Attributes + +18.1.1. SYNOPSIS + + fh, attr_request -> attrmask, attr_vals + +18.1.2. ARGUMENT + + struct CB_GETATTR4args { + nfs_fh4 fh; + bitmap4 attr_request; + }; + +18.1.3. RESULT + + struct CB_GETATTR4resok { + fattr4 obj_attributes; + }; + + union CB_GETATTR4res switch (nfsstat4 status) { + case NFS4_OK: + CB_GETATTR4resok resok4; + default: + void; + }; + +18.1.4. DESCRIPTION + + The CB_GETATTR operation is used by the server to obtain the current + modified state of a file that has been OPEN_DELEGATE_WRITE delegated. + The size attribute and the change attribute are the only ones + guaranteed to be serviced by the client. See Section 10.4.3 for a + full description of how the client and server are to interact with + the use of CB_GETATTR. + + If the filehandle specified is not one for which the client holds an + OPEN_DELEGATE_WRITE delegation, an NFS4ERR_BADHANDLE error is + returned. + +18.1.5. IMPLEMENTATION + + The client returns attrmask bits and the associated attribute values + only for the change attribute, and attributes that it may change + (time_modify and size). + + + + + +Haynes & Noveck Standards Track [Page 309] + +RFC 7530 NFSv4 March 2015 + + +18.2. Operation 4: CB_RECALL - Recall an Open Delegation + +18.2.1. SYNOPSIS + + stateid, truncate, fh -> () + +18.2.2. ARGUMENT + + struct CB_RECALL4args { + stateid4 stateid; + bool truncate; + nfs_fh4 fh; + }; + +18.2.3. RESULT + + struct CB_RECALL4res { + nfsstat4 status; + }; + +18.2.4. DESCRIPTION + + The CB_RECALL operation is used to begin the process of recalling an + open delegation and returning it to the server. + + The truncate flag is used to optimize a recall for a file that is + about to be truncated to zero. When it is set, the client is freed + of obligation to propagate modified data for the file to the server, + since this data is irrelevant. + + If the handle specified is not one for which the client holds an open + delegation, an NFS4ERR_BADHANDLE error is returned. + + If the stateid specified is not one corresponding to an open + delegation for the file specified by the filehandle, an + NFS4ERR_BAD_STATEID is returned. + +18.2.5. IMPLEMENTATION + + The client should reply to the callback immediately. Replying does + not complete the recall, except when an error was returned. The + recall is not complete until the delegation is returned using a + DELEGRETURN. + + + + + + + + +Haynes & Noveck Standards Track [Page 310] + +RFC 7530 NFSv4 March 2015 + + +18.3. Operation 10044: CB_ILLEGAL - Illegal Callback Operation + +18.3.1. SYNOPSIS + + -> () + +18.3.2. ARGUMENT + + void; + +18.3.3. RESULT + + /* + * CB_ILLEGAL: Response for illegal operation numbers + */ + struct CB_ILLEGAL4res { + nfsstat4 status; + }; + +18.3.4. DESCRIPTION + + This operation is a placeholder for encoding a result to handle the + case of the client sending an operation code within COMPOUND that is + not supported. See Section 15.2.4 for more details. + + The status field of CB_ILLEGAL4res MUST be set to NFS4ERR_OP_ILLEGAL. + +18.3.5. IMPLEMENTATION + + A server will probably not send an operation with code OP_CB_ILLEGAL, + but if it does, the response will be CB_ILLEGAL4res, just as it would + be with any other invalid operation code. Note that if the client + gets an illegal operation code that is not OP_ILLEGAL, and if the + client checks for legal operation codes during the XDR decode phase, + then the CB_ILLEGAL4res would not be returned. + + + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 311] + +RFC 7530 NFSv4 March 2015 + + +19. Security Considerations + + NFS has historically used a model where, from an authentication + perspective, the client was the entire machine, or at least the + source IP address of the machine. The NFS server relied on the NFS + client to make the proper authentication of the end-user. The NFS + server in turn shared its files only to specific clients, as + identified by the client's source IP address. Given this model, the + AUTH_SYS RPC security flavor simply identified the end-user using the + client to the NFS server. When processing NFS responses, the client + ensured that the responses came from the same IP address and port + number that the request was sent to. While such a model is easy to + implement and simple to deploy and use, it is certainly not a safe + model. Thus, NFSv4 mandates that implementations support a security + model that uses end-to-end authentication, where an end-user on a + client mutually authenticates (via cryptographic schemes that do not + expose passwords or keys in the clear on the network) to a principal + on an NFS server. Consideration should also be given to the + integrity and privacy of NFS requests and responses. The issues of + end-to-end mutual authentication, integrity, and privacy are + discussed as part of Section 3. + + When an NFSv4 mandated security model is used and a security + principal or an NFSv4 name in user@dns_domain form needs to be + translated to or from a local representation as described in + Section 5.9, the translation SHOULD be done in a secure manner that + preserves the integrity of the translation. For communication with a + name service such as the Lightweight Directory Access Protocol (LDAP) + ([RFC4511]), this means employing a security service that uses + authentication and data integrity. Kerberos and Transport Layer + Security (TLS) ([RFC5246]) are examples of such a security service. + + Note that being REQUIRED to implement does not mean REQUIRED to use; + AUTH_SYS can be used by NFSv4 clients and servers. However, AUTH_SYS + is merely an OPTIONAL security flavor in NFSv4, and so + interoperability via AUTH_SYS is not assured. + + For reasons of reduced administration overhead, better performance, + and/or reduction of CPU utilization, users of NFSv4 implementations + may choose to not use security mechanisms that enable integrity + protection on each remote procedure call and response. The use of + mechanisms without integrity leaves the customer vulnerable to an + attacker in between the NFS client and server that modifies the RPC + request and/or the response. While implementations are free to + provide the option to use weaker security mechanisms, there are two + operations in particular that warrant the implementation overriding + user choices. + + + + +Haynes & Noveck Standards Track [Page 312] + +RFC 7530 NFSv4 March 2015 + + + The first such operation is SECINFO. It is recommended that the + client issue the SECINFO call such that it is protected with a + security flavor that has integrity protection, such as RPCSEC_GSS + with a security triple that uses either rpc_gss_svc_integrity or + rpc_gss_svc_privacy (rpc_gss_svc_privacy includes integrity + protection) service. Without integrity protection encapsulating + SECINFO and therefore its results, an attacker in the middle could + modify results such that the client might select a weaker algorithm + in the set allowed by the server, making the client and/or server + vulnerable to further attacks. + + The second operation that SHOULD use integrity protection is any + GETATTR for the fs_locations attribute. The attack has two steps. + First, the attacker modifies the unprotected results of some + operation to return NFS4ERR_MOVED. Second, when the client follows + up with a GETATTR for the fs_locations attribute, the attacker + modifies the results to cause the client to migrate its traffic to a + server controlled by the attacker. + + Because the operations SETCLIENTID/SETCLIENTID_CONFIRM are + responsible for the release of client state, it is imperative that + the principal used for these operations is checked against and + matches with the previous use of these operations. See Section 9.1.1 + for further discussion. + + Unicode in the form of UTF-8 is used for file component names (i.e., + both directory and file components), as well as the owner and + owner_group attributes; other character sets may also be allowed for + file component names. String processing (e.g., Unicode + normalization) raises security concerns for string comparison. See + Sections 5.9 and 12 for further discussion, and see [RFC6943] for + related identifier comparison security considerations. File + component names are identifiers with respect to the identifier + comparison discussion in [RFC6943] because they are used to identify + the objects to which ACLs are applied; see Section 6. + + + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 313] + +RFC 7530 NFSv4 March 2015 + + +20. IANA Considerations + + This section uses terms that are defined in [RFC5226]. + +20.1. Named Attribute Definitions + + IANA has created a registry called the "NFSv4 Named Attribute + Definitions Registry" for [RFC3530] and [RFC5661]. This section + introduces no new changes, but it does recap the intent. + + The NFSv4 protocol supports the association of a file with zero or + more named attributes. The namespace identifiers for these + attributes are defined as string names. The protocol does not define + the specific assignment of the namespace for these file attributes. + The IANA registry promotes interoperability where common interests + exist. While application developers are allowed to define and use + attributes as needed, they are encouraged to register the attributes + with IANA. + + Such registered named attributes are presumed to apply to all minor + versions of NFSv4, including those defined subsequently to the + registration. Where the named attribute is intended to be limited + with regard to the minor versions for which they are not to be used, + the assignment in the registry will clearly state the applicable + limits. + + The registry is to be maintained using the Specification Required + policy as defined in Section 4.1 of [RFC5226]. + + Under the NFSv4 specification, the name of a named attribute can in + theory be up to 2^32 - 1 bytes in length, but in practice NFSv4 + clients and servers will be unable to handle a string that long. + IANA should reject any assignment request with a named attribute that + exceeds 128 UTF-8 characters. To give the IESG the flexibility to + set up bases of assignment of Experimental Use and Standards Action, + the prefixes of "EXPE" and "STDS" are Reserved. The zero-length + named attribute name is Reserved. + + The prefix "PRIV" is allocated for Private Use. A site that wants to + make use of unregistered named attributes without risk of conflicting + with an assignment in IANA's registry should use the prefix "PRIV" in + all of its named attributes. + + + + + + + + + +Haynes & Noveck Standards Track [Page 314] + +RFC 7530 NFSv4 March 2015 + + + Because some NFSv4 clients and servers have case-insensitive + semantics, the fifteen additional lowercase and mixed-case + permutations of each of "EXPE", "PRIV", and "STDS" are Reserved + (e.g., "expe", "expE", "exPe", etc. are Reserved). Similarly, IANA + must not allow two assignments that would conflict if both named + attributes were converted to a common case. + + The registry of named attributes is a list of assignments, each + containing three fields for each assignment. + + 1. A US-ASCII string name that is the actual name of the attribute. + This name must be unique. This string name can be 1 to 128 UTF-8 + characters long. + + 2. A reference to the specification of the named attribute. The + reference can consume up to 256 bytes (or more, if IANA permits). + + 3. The point of contact of the registrant. The point of contact can + consume up to 256 bytes (or more, if IANA permits). + +20.1.1. Initial Registry + + There is no initial registry. + +20.1.2. Updating Registrations + + The registrant is always permitted to update the point of contact + field. To make any other change will require Expert Review or IESG + Approval. + +20.2. Updates to Existing IANA Registries + + In addition, because this document obsoletes RFC 3530, IANA has + + o replaced all references to RFC 3530 in the Network Identifier + (r_netid) registry with references to this document. + + o replaced the reference to the nfs registration's reference to + RFC 3530 in the GSSAPI/Kerberos/SASL Service names registry with a + reference to this document. + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 315] + +RFC 7530 NFSv4 March 2015 + + +21. References + +21.1. Normative References + + [RFC20] Cerf, V., "ASCII format for network interchange", STD 80, + RFC 20, October 1969, + . + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997, + . + + [RFC2203] Eisler, M., Chiu, A., and L. Ling, "RPCSEC_GSS Protocol + Specification", RFC 2203, September 1997, + . + + [RFC2743] Linn, J., "Generic Security Service Application Program + Interface Version 2, Update 1", RFC 2743, January 2000, + . + + [RFC3490] Faltstrom, P., Hoffman, P., and A. Costello, + "Internationalizing Domain Names in Applications (IDNA)", + RFC 3490, March 2003, + . + + [RFC3492] Costello, A., "Punycode: A Bootstring encoding of Unicode + for Internationalized Domain Names in Applications + (IDNA)", RFC 3492, March 2003, + . + + [RFC3629] Yergeau, F., "UTF-8, a transformation format of + ISO 10646", STD 63, RFC 3629, November 2003, + . + + [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an + IANA Considerations Section in RFCs", BCP 26, RFC 5226, + May 2008, . + + [RFC5403] Eisler, M., "RPCSEC_GSS Version 2", RFC 5403, + February 2009, . + + [RFC5531] Thurlow, R., "RPC: Remote Procedure Call Protocol + Specification Version 2", RFC 5531, May 2009, + . + + + + + + + +Haynes & Noveck Standards Track [Page 316] + +RFC 7530 NFSv4 March 2015 + + + [RFC5665] Eisler, M., "IANA Considerations for Remote Procedure Call + (RPC) Network Identifiers and Universal Address Formats", + RFC 5665, January 2010, + . + + [RFC5890] Klensin, J., "Internationalized Domain Names for + Applications (IDNA): Definitions and Document Framework", + RFC 5890, August 2010, + . + + [RFC5891] Klensin, J., "Internationalized Domain Names in + Applications (IDNA): Protocol", RFC 5891, August 2010, + . + + [RFC6649] Hornquist Astrand, L. and T. Yu, "Deprecate DES, + RC4-HMAC-EXP, and Other Weak Cryptographic Algorithms in + Kerberos", BCP 179, RFC 6649, July 2012, + . + + [RFC7531] Haynes, T., Ed., and D. Noveck, Ed., "Network File System + (NFS) Version 4 External Data Representation Standard + (XDR) Description", RFC 7531, March 2015, + . + + [SPECIALCASING] + The Unicode Consortium, "SpecialCasing-7.0.0.txt", Unicode + Character Database, March 2014, . + + [UNICODE] The Unicode Consortium, "The Unicode Standard, + Version 7.0.0", (Mountain View, CA: The Unicode + Consortium, 2014 ISBN 978-1-936213-09-2), June 2014, + . + + [openg_symlink] + The Open Group, "Section 3.372 of Chapter 3 of Base + Definitions of The Open Group Base Specifications + Issue 7", IEEE Std 1003.1, 2013 Edition (HTML Version), + ISBN 1937218287, April 2013, . + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 317] + +RFC 7530 NFSv4 March 2015 + + +21.2. Informative References + + [Chet] Juszczak, C., "Improving the Performance and Correctness + of an NFS Server", USENIX Conference Proceedings, + June 1990. + + [Floyd] Floyd, S. and V. Jacobson, "The Synchronization of + Periodic Routing Messages", IEEE/ACM Transactions on + Networking 2(2), pp. 122-136, April 1994. + + [IESG_ERRATA] + IESG, "IESG Processing of RFC Errata for the IETF Stream", + July 2008. + + [MS-SMB] Microsoft Corporation, "Server Message Block (SMB) + Protocol Specification", MS-SMB 43.0, May 2014. + + [P1003.1e] + Institute of Electrical and Electronics Engineers, Inc., + "IEEE Draft P1003.1e", 1997. + + [RFC1094] Nowicki, B., "NFS: Network File System Protocol + specification", RFC 1094, March 1989, + . + + [RFC1813] Callaghan, B., Pawlowski, B., and P. Staubach, "NFS + Version 3 Protocol Specification", RFC 1813, June 1995, + . + + [RFC1833] Srinivasan, R., "Binding Protocols for ONC RPC Version 2", + RFC 1833, August 1995, + . + + [RFC2054] Callaghan, B., "WebNFS Client Specification", RFC 2054, + October 1996, . + + [RFC2055] Callaghan, B., "WebNFS Server Specification", RFC 2055, + October 1996, . + + [RFC2224] Callaghan, B., "NFS URL Scheme", RFC 2224, October 1997, + . + + [RFC2623] Eisler, M., "NFS Version 2 and Version 3 Security Issues + and the NFS Protocol's Use of RPCSEC_GSS and Kerberos V5", + RFC 2623, June 1999, + . + + + + + +Haynes & Noveck Standards Track [Page 318] + +RFC 7530 NFSv4 March 2015 + + + [RFC2624] Shepler, S., "NFS Version 4 Design Considerations", + RFC 2624, June 1999, + . + + [RFC2755] Chiu, A., Eisler, M., and B. Callaghan, "Security + Negotiation for WebNFS", RFC 2755, January 2000, + . + + [RFC3010] Shepler, S., Callaghan, B., Robinson, D., Thurlow, R., + Beame, C., Eisler, M., and D. Noveck, "NFS version 4 + Protocol", RFC 3010, December 2000, + . + + [RFC3232] Reynolds, J., Ed., "Assigned Numbers: RFC 1700 is Replaced + by an On-line Database", RFC 3232, January 2002, + . + + [RFC3530] Shepler, S., Callaghan, B., Robinson, D., Thurlow, R., + Beame, C., Eisler, M., and D. Noveck, "Network File System + (NFS) version 4 Protocol", RFC 3530, April 2003, + . + + [RFC4121] Zhu, L., Jaganathan, K., and S. Hartman, "The Kerberos + Version 5 Generic Security Service Application Program + Interface (GSS-API) Mechanism: Version 2", RFC 4121, + July 2005, . + + [RFC4178] Zhu, L., Leach, P., Jaganathan, K., and W. Ingersoll, "The + Simple and Protected Generic Security Service Application + Program Interface (GSS-API) Negotiation Mechanism", + RFC 4178, October 2005, + . + + [RFC4506] Eisler, M., Ed., "XDR: External Data Representation + Standard", STD 67, RFC 4506, May 2006, + . + + [RFC4511] Sermersheim, J., Ed., "Lightweight Directory Access + Protocol (LDAP): The Protocol", RFC 4511, June 2006, + . + + [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security + (TLS) Protocol Version 1.2", RFC 5246, August 2008, + . + + + + + + + +Haynes & Noveck Standards Track [Page 319] + +RFC 7530 NFSv4 March 2015 + + + [RFC5661] Shepler, S., Ed., Eisler, M., Ed., and D. Noveck, Ed., + "Network File System (NFS) Version 4 Minor Version 1 + Protocol", RFC 5661, January 2010, + . + + [RFC6365] Hoffman, P. and J. Klensin, "Terminology Used in + Internationalization in the IETF", BCP 166, RFC 6365, + September 2011, . + + [RFC6943] Thaler, D., Ed., "Issues in Identifier Comparison for + Security Purposes", RFC 6943, May 2013, + . + + [fcntl] The Open Group, "Section 'fcntl()' of System Interfaces of + The Open Group Base Specifications Issue 7", IEEE + Std 1003.1, 2013 Edition (HTML Version), ISBN 1937218287, + April 2013, . + + [fsync] The Open Group, "Section 'fsync()' of System Interfaces of + The Open Group Base Specifications Issue 7", IEEE + Std 1003.1, 2013 Edition (HTML Version), ISBN 1937218287, + April 2013, . + + [getpwnam] + The Open Group, "Section 'getpwnam()' of System Interfaces + of The Open Group Base Specifications Issue 7", IEEE + Std 1003.1, 2013 Edition (HTML Version), ISBN 1937218287, + April 2013, . + + [read_api] + The Open Group, "Section 'read()' of System Interfaces of + The Open Group Base Specifications Issue 7", IEEE + Std 1003.1, 2013 Edition (HTML Version), ISBN 1937218287, + April 2013, . + + [readdir_api] + The Open Group, "Section 'readdir()' of System Interfaces + of The Open Group Base Specifications Issue 7", IEEE + Std 1003.1, 2013 Edition (HTML Version), ISBN 1937218287, + April 2013, . + + [stat] The Open Group, "Section 'stat()' of System Interfaces of + The Open Group Base Specifications Issue 7", IEEE + Std 1003.1, 2013 Edition (HTML Version), ISBN 1937218287, + April 2013, . + + + + + + +Haynes & Noveck Standards Track [Page 320] + +RFC 7530 NFSv4 March 2015 + + + [unlink] The Open Group, "Section 'unlink()' of System Interfaces + of The Open Group Base Specifications Issue 7", IEEE + Std 1003.1, 2013 Edition (HTML Version), ISBN 1937218287, + April 2013, . + + [write_api] + The Open Group, "Section 'write()' of System Interfaces of + The Open Group Base Specifications Issue 7", IEEE + Std 1003.1, 2013 Edition (HTML Version), ISBN 1937218287, + April 2013, . + + [xnfs] The Open Group, "Protocols for Interworking: XNFS, + Version 3W, ISBN 1-85912-184-5", February 1998. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 321] + +RFC 7530 NFSv4 March 2015 + + +Acknowledgments + + A bis is certainly built on the shoulders of the first attempt. + Spencer Shepler, Brent Callaghan, David Robinson, Robert Thurlow, + Carl Beame, Mike Eisler, and David Noveck are responsible for a great + deal of the effort in this work. + + Tom Haynes would like to thank NetApp, Inc. for its funding of his + time on this project. + + Rob Thurlow clarified how a client should contact a new server if a + migration has occurred. + + David Black, Nico Williams, Mike Eisler, Trond Myklebust, James + Lentini, and Mike Kupfer read many earlier draft versions of + Section 12 and contributed numerous useful suggestions, without which + the necessary revision of that section for this document would not + have been possible. + + Peter Staubach read almost all of the earlier draft versions of + Section 12, leading to the published result, and his numerous + comments were always useful and contributed substantially to + improving the quality of the final result. + + Peter Saint-Andre was gracious enough to read the most recent draft + version of Section 12 and provided some key insight as to the + concerns of the Internationalization community. + + James Lentini graciously read the rewrite of Section 8, and his + comments were vital in improving the quality of that effort. + + Rob Thurlow, Sorin Faibish, James Lentini, Bruce Fields, and Trond + Myklebust were faithful attendants of the biweekly triage meeting and + accepted many an action item. + + Bruce Fields was a good sounding board for both the third edge + condition and courtesy locks in general. He was also the leading + advocate of stamping out backport issues from [RFC5661]. + + Marcel Telka was a champion of straightening out the difference + between a lock-owner and an open-owner. He has also been diligent in + reviewing the final document. + + Benjamin Kaduk reminded us that DES is dead, and Nico Williams helped + us close the lid on the coffin. + + Elwyn Davies provided a very thorough and engaging Gen-ART review; + thanks! + + + +Haynes & Noveck Standards Track [Page 322] + +RFC 7530 NFSv4 March 2015 + + +Authors' Addresses + + Thomas Haynes (editor) + Primary Data, Inc. + 4300 El Camino Real Ste 100 + Los Altos, CA 94022 + United States + + Phone: +1 408 215 1519 + EMail: thomas.haynes@primarydata.com + + + David Noveck (editor) + Dell + 300 Innovative Way + Nashua, NH 03062 + United States + + Phone: +1 781 572 8038 + EMail: dave_noveck@dell.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Haynes & Noveck Standards Track [Page 323] + -- cgit v1.2.3