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.

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

   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

   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

      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

   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

      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