tech-invite   World Map     

3GPP     Specs     Glossaries     Architecture     IMS     UICC       IETF     RFCs     Groups     SIP     ABNFs       Search

RFC 3530


Pages: 275
Top     in Index     Prev     Next
 

Network File System (NFS) version 4 Protocol

Part 1 of 8, p. 1 to 16
None       Next RFC Part

Obsoleted by:    7530
Obsoletes:    3010


Top       ToC       Page 1 
Network Working Group                                         S. Shepler
Request for Comments: 3530                                  B. Callaghan
Obsoletes: 3010                                              D. Robinson
Category: Standards Track                                     R. Thurlow
                                                  Sun Microsystems, Inc.
                                                                C. Beame
                                                        Hummingbird Ltd.
                                                               M. Eisler
                                                               D. Noveck
                                                 Network Appliance, Inc.
                                                              April 2003


              Network File System (NFS) version 4 Protocol

Status of this Memo

   This document specifies an Internet standards track protocol for the
   Internet community, and requests discussion and suggestions for
   improvements.  Please refer to the current edition of the "Internet
   Official Protocol Standards" (STD 1) for the standardization state
   and status of this protocol.  Distribution of this memo is unlimited.

Copyright Notice

   Copyright (C) The Internet Society (2003).  All Rights Reserved.

Abstract

   The Network File System (NFS) version 4 is a distributed filesystem
   protocol which owes heritage to 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 have been added.  Of course,
   attention has been applied to making NFS version 4 operate well in an
   Internet environment.

   This document replaces RFC 3010 as the definition of the NFS version
   4 protocol.

Key Words

   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 [RFC2119].

Top       Page 2 
Table of Contents

   1.   Introduction . . . . . . . . . . . . . . . . . . . . . . .    8
        1.1.  Changes since RFC 3010 . . . . . . . . . . . . . . .    8
        1.2.  NFS version 4 Goals. . . . . . . . . . . . . . . . .    9
        1.3.  Inconsistencies of this Document with Section 18 . .    9
        1.4.  Overview of NFS version 4 Features . . . . . . . . .   10
              1.4.1.  RPC and Security . . . . . . . . . . . . . .   10
              1.4.2.  Procedure and Operation Structure. . . . . .   10
              1.4.3.  Filesystem Mode. . . . . . . . . . . . . . .   11
                      1.4.3.1.  Filehandle Types . . . . . . . . .   11
                      1.4.3.2.  Attribute Types. . . . . . . . . .   12
                      1.4.3.3.  Filesystem Replication and
                                Migration. . . . . . . . . . . . .   13
              1.4.4.  OPEN and CLOSE . . . . . . . . . . . . . . .   13
              1.4.5.  File locking . . . . . . . . . . . . . . . .   13
              1.4.6.  Client Caching and Delegation. . . . . . . .   13
        1.5.  General Definitions. . . . . . . . . . . . . . . . .   14
   2.   Protocol Data Types. . . . . . . . . . . . . . . . . . . .   16
        2.1.  Basic Data Types . . . . . . . . . . . . . . . . . .   16
        2.2.  Structured Data Types. . . . . . . . . . . . . . . .   18
   3.   RPC and Security Flavor. . . . . . . . . . . . . . . . . .   23
        3.1.  Ports and Transports . . . . . . . . . . . . . . . .   23
              3.1.1.  Client Retransmission Behavior . . . . . . .   24
        3.2.  Security Flavors . . . . . . . . . . . . . . . . . .   25
              3.2.1.  Security mechanisms for NFS version 4. . . .   25
                      3.2.1.1.  Kerberos V5 as a security triple .   25
                      3.2.1.2.  LIPKEY as a security triple. . . .   26
                      3.2.1.3.  SPKM-3 as a security triple. . . .   27
        3.3.  Security Negotiation . . . . . . . . . . . . . . . .   27
              3.3.1.  SECINFO. . . . . . . . . . . . . . . . . . .   28
              3.3.2.  Security Error . . . . . . . . . . . . . . .   28
        3.4.  Callback RPC Authentication. . . . . . . . . . . . .   28
   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.   File Attributes. . . . . . . . . . . . . . . . . . . . . .   35
        5.1.  Mandatory Attributes . . . . . . . . . . . . . . . .   37
        5.2.  Recommended Attributes . . . . . . . . . . . . . . .   37
        5.3.  Named Attributes . . . . . . . . . . . . . . . . . .   37

Top      ToC       Page 3 
        5.4.  Classification of Attributes . . . . . . . . . . . .   38
        5.5.  Mandatory Attributes - Definitions . . . . . . . . .   39
        5.6.  Recommended Attributes - Definitions . . . . . . . .   41
        5.7.  Time Access. . . . . . . . . . . . . . . . . . . . .   46
        5.8.  Interpreting owner and owner_group . . . . . . . . .   47
        5.9.  Character Case Attributes. . . . . . . . . . . . . .   49
        5.10. Quota Attributes . . . . . . . . . . . . . . . . . .   49
        5.11. Access Control Lists . . . . . . . . . . . . . . . .   50
               5.11.1.  ACE type . . . . . . . . . . . . . . . . .   51
               5.11.2.  ACE Access Mask. . . . . . . . . . . . . .   52
               5.11.3.  ACE flag . . . . . . . . . . . . . . . . .   54
               5.11.4.  ACE who  . . . . . . . . . . . . . . . . .   55
               5.11.5.  Mode Attribute . . . . . . . . . . . . . .   56
               5.11.6.  Mode and ACL Attribute . . . . . . . . . .   57
               5.11.7.  mounted_on_fileid. . . . . . . . . . . . .   57
   6.  Filesystem Migration and Replication  . . . . . . . . . . .   58
        6.1.  Replication. . . . . . . . . . . . . . . . . . . . .   58
        6.2.  Migration. . . . . . . . . . . . . . . . . . . . . .   59
        6.3.  Interpretation of the fs_locations Attribute . . . .   60
        6.4.  Filehandle Recovery for Migration or Replication . .   61
   7.  NFS Server Name Space . . . . . . . . . . . . . . . . . . .   61
        7.1.  Server Exports . . . . . . . . . . . . . . . . . . .   61
        7.2.  Browsing Exports . . . . . . . . . . . . . . . . . .   62
        7.3.  Server Pseudo Filesystem . . . . . . . . . . . . . .   62
        7.4.  Multiple Roots . . . . . . . . . . . . . . . . . . .   63
        7.5.  Filehandle Volatility. . . . . . . . . . . . . . . .   63
        7.6.  Exported Root. . . . . . . . . . . . . . . . . . . .   63
        7.7.  Mount Point Crossing . . . . . . . . . . . . . . . .   63
        7.8.  Security Policy and Name Space Presentation. . . . .   64
   8.   File Locking and Share Reservations. . . . . . . . . . . .   65
        8.1.  Locking. . . . . . . . . . . . . . . . . . . . . . .   65
              8.1.1.    Client ID. . . . . . . . . . . . . . . . .   66
              8.1.2.    Server Release of Clientid . . . . . . . .   69
              8.1.3.    lock_owner and stateid Definition. . . . .   69
              8.1.4.    Use of the stateid and Locking . . . . . .   71
              8.1.5.    Sequencing of Lock Requests. . . . . . . .   73
              8.1.6.    Recovery from Replayed Requests. . . . . .   74
              8.1.7.    Releasing lock_owner State . . . . . . . .   74
              8.1.8.    Use of Open Confirmation . . . . . . . . .   75
        8.2.  Lock Ranges. . . . . . . . . . . . . . . . . . . . .   76
        8.3.  Upgrading and Downgrading Locks. . . . . . . . . . .   76
        8.4.  Blocking Locks . . . . . . . . . . . . . . . . . . .   77
        8.5.  Lease Renewal. . . . . . . . . . . . . . . . . . . .   77
        8.6.  Crash Recovery . . . . . . . . . . . . . . . . . . .   78
               8.6.1.   Client Failure and Recovery. . . . . . . .   79
               8.6.2.   Server Failure and Recovery. . . . . . . .   79
               8.6.3.   Network Partitions and Recovery. . . . . .   81
        8.7.   Recovery from a Lock Request Timeout or Abort . . .   85

Top      ToC       Page 4 
        8.8.   Server Revocation of Locks. . . . . . . . . . . . .   85
        8.9.   Share Reservations. . . . . . . . . . . . . . . . .   86
        8.10.  OPEN/CLOSE Operations . . . . . . . . . . . . . . .   87
               8.10.1.  Close and Retention of State
                        Information. . . . . . . . . . . . . . . .   88
        8.11.  Open Upgrade and Downgrade. . . . . . . . . . . . .   88
        8.12.  Short and Long Leases . . . . . . . . . . . . . . .   89
        8.13.  Clocks, Propagation Delay, and Calculating Lease
               Expiration. . . . . . . . . . . . . . . . . . . . .   89
        8.14.  Migration, Replication and State. . . . . . . . . .   90
               8.14.1.  Migration and State. . . . . . . . . . . .   90
               8.14.2.  Replication and State. . . . . . . . . . .   91
               8.14.3.  Notification of Migrated Lease . . . . . .   92
               8.14.4.  Migration and the Lease_time Attribute . .   92
   9.  Client-Side Caching . . . . . . . . . . . . . . . . . . . .   93
        9.1.   Performance Challenges for Client-Side Caching. . .   93
        9.2.   Delegation and Callbacks. . . . . . . . . . . . . .   94
               9.2.1.  Delegation Recovery . . . . . . . . . . . .   96
        9.3.   Data Caching. . . . . . . . . . . . . . . . . . . .   98
               9.3.1.   Data Caching and OPENs . . . . . . . . . .   98
               9.3.2.   Data Caching and File Locking. . . . . . .   99
               9.3.3.   Data Caching and Mandatory File Locking. .  101
               9.3.4.   Data Caching and File Identity . . . . . .  101
        9.4.   Open Delegation . . . . . . . . . . . . . . . . . .  102
               9.4.1.   Open Delegation and Data Caching . . . . .  104
               9.4.2.   Open Delegation and File Locks . . . . . .  106
               9.4.3.   Handling of CB_GETATTR . . . . . . . . . .  106
               9.4.4.   Recall of Open Delegation. . . . . . . . .  109
               9.4.5.   Clients that Fail to Honor
                        Delegation Recalls . . . . . . . . . . . .  111
               9.4.6.   Delegation Revocation. . . . . . . . . . .  112
        9.5.   Data Caching and Revocation . . . . . . . . . . . .  112
               9.5.1.   Revocation Recovery for Write Open
                        Delegation . . . . . . . . . . . . . . . .  113
        9.6.   Attribute Caching . . . . . . . . . . . . . . . . .  113
        9.7.   Data and Metadata Caching and Memory Mapped Files .  115
        9.8.   Name Caching  . . . . . . . . . . . . . . . . . . .  118
        9.9.   Directory Caching . . . . . . . . . . . . . . . . .  119
   10.  Minor Versioning . . . . . . . . . . . . . . . . . . . . .  120
   11.  Internationalization . . . . . . . . . . . . . . . . . . .  122
        11.1.  Stringprep profile for the utf8str_cs type. . . . .  123
               11.1.1.  Intended applicability of the
                        nfs4_cs_prep profile . . . . . . . . . . .  123
               11.1.2.  Character repertoire of nfs4_cs_prep . . .  124
               11.1.3.  Mapping used by nfs4_cs_prep . . . . . . .  124
               11.1.4.  Normalization used by nfs4_cs_prep . . . .  124
               11.1.5.  Prohibited output for nfs4_cs_prep . . . .  125
               11.1.6.  Bidirectional output for nfs4_cs_prep. . .  125

Top      ToC       Page 5 
        11.2.  Stringprep profile for the utf8str_cis type . . . .  125
               11.2.1.  Intended applicability of the
                        nfs4_cis_prep profile. . . . . . . . . . .  125
               11.2.2.  Character repertoire of nfs4_cis_prep  . .  125
               11.2.3.  Mapping used by nfs4_cis_prep  . . . . . .  125
               11.2.4.  Normalization used by nfs4_cis_prep  . . .  125
               11.2.5.  Prohibited output for nfs4_cis_prep  . . .  126
               11.2.6.  Bidirectional output for nfs4_cis_prep . .  126
        11.3.  Stringprep profile for the utf8str_mixed type . . .  126
               11.3.1.  Intended applicability of the
                        nfs4_mixed_prep profile. . . . . . . . . .  126
               11.3.2.  Character repertoire of nfs4_mixed_prep  .  126
               11.3.3.  Mapping used by nfs4_cis_prep  . . . . . .  126
               11.3.4.  Normalization used by nfs4_mixed_prep  . .  127
               11.3.5.  Prohibited output for nfs4_mixed_prep  . .  127
               11.3.6.  Bidirectional output for nfs4_mixed_prep .  127
        11.4.  UTF-8 Related Errors. . . . . . . . . . . . . . . .  127
   12.  Error Definitions  . . . . . . . . . . . . . . . . . . . .  128
   13.  NFS version 4 Requests . . . . . . . . . . . . . . . . . .  134
        13.1.  Compound Procedure. . . . . . . . . . . . . . . . .  134
        13.2.  Evaluation of a Compound Request. . . . . . . . . .  135
        13.3.  Synchronous Modifying Operations. . . . . . . . . .  136
        13.4.  Operation Values. . . . . . . . . . . . . . . . . .  136
   14.  NFS version 4 Procedures . . . . . . . . . . . . . . . . .  136
        14.1.  Procedure 0: NULL - No Operation. . . . . . . . . .  136
        14.2.  Procedure 1: COMPOUND - Compound Operations . . . .  137
               14.2.1.   Operation 3: ACCESS - Check Access
                         Rights. . . . . . . . . . . . . . . . . .  140
               14.2.2.   Operation 4: CLOSE - Close File . . . . .  142
               14.2.3.   Operation 5: COMMIT - Commit
                         Cached Data . . . . . . . . . . . . . . .  144
               14.2.4.   Operation 6: CREATE - Create a
                         Non-Regular File Object . . . . . . . . .  147
               14.2.5.   Operation 7: DELEGPURGE -
                         Purge Delegations Awaiting Recovery . . .  150
               14.2.6.   Operation 8: DELEGRETURN - Return
                         Delegation. . . . . . . . . . . . . . . .  151
               14.2.7.   Operation 9: GETATTR - Get Attributes . .  152
               14.2.8.   Operation 10: GETFH - Get Current
                         Filehandle. . . . . . . . . . . . . . . .  153
               14.2.9.   Operation 11: LINK - Create Link to a
                         File. . . . . . . . . . . . . . . . . . .  154
               14.2.10.  Operation 12: LOCK - Create Lock  . . . .  156
               14.2.11.  Operation 13: LOCKT - Test For Lock . . .  160
               14.2.12.  Operation 14: LOCKU - Unlock File . . . .  162
               14.2.13.  Operation 15: LOOKUP - Lookup Filename. .  163
               14.2.14.  Operation 16: LOOKUPP - Lookup
                         Parent Directory. . . . . . . . . . . . .  165

Top      ToC       Page 6 
               14.2.15.  Operation 17: NVERIFY - Verify
                         Difference in Attributes  . . . . . . . .  166
               14.2.16.  Operation 18: OPEN - Open a Regular
                         File. . . . . . . . . . . . . . . . . . .  168
               14.2.17.  Operation 19: OPENATTR - Open Named
                         Attribute Directory . . . . . . . . . . .  178
               14.2.18.  Operation 20: OPEN_CONFIRM -
                         Confirm Open . . . . . . . . . . . . . .   180
               14.2.19.  Operation 21: OPEN_DOWNGRADE -
                         Reduce Open File Access . . . . . . . . .  182
               14.2.20.  Operation 22: PUTFH - Set
                         Current Filehandle. . . . . . . . . . . .  184
               14.2.21.  Operation 23: PUTPUBFH -
                         Set Public Filehandle . . . . . . . . . .  185
               14.2.22.  Operation 24: PUTROOTFH -
                         Set Root Filehandle . . . . . . . . . . .  186
               14.2.23.  Operation 25: READ - Read from File . . .  187
               14.2.24.  Operation 26: READDIR -
                         Read Directory. . . . . . . . . . . . . .  190
               14.2.25.  Operation 27: READLINK -
                         Read Symbolic Link. . . . . . . . . . . .  193
               14.2.26.  Operation 28: REMOVE -
                         Remove Filesystem Object. . . . . . . . .  195
               14.2.27.  Operation 29: RENAME -
                         Rename Directory Entry. . . . . . . . . .  197
               14.2.28.  Operation 30: RENEW - Renew a Lease . . .  200
               14.2.29.  Operation 31: RESTOREFH -
                         Restore Saved Filehandle. . . . . . . . .  201
               14.2.30.  Operation 32: SAVEFH - Save
                         Current Filehandle. . . . . . . . . . . .  202
               14.2.31.  Operation 33: SECINFO - Obtain
                         Available Security. . . . . . . . . . . .  203
               14.2.32.  Operation 34: SETATTR - Set Attributes. .  206
               14.2.33.  Operation 35: SETCLIENTID -
                         Negotiate Clientid. . . . . . . . . . . .  209
               14.2.34.  Operation 36: SETCLIENTID_CONFIRM -
                         Confirm Clientid. . . . . . . . . . . . .  213
               14.2.35.  Operation 37: VERIFY -
                         Verify Same Attributes. . . . . . . . . .  217
               14.2.36.  Operation 38: WRITE - Write to File . . .  218
               14.2.37.  Operation 39: RELEASE_LOCKOWNER -
                         Release Lockowner State . . . . . . . . .  223
               14.2.38.  Operation 10044: ILLEGAL -
                         Illegal operation . . . . . . . . . . . .  224
   15.  NFS version 4 Callback Procedures  . . . . . . . . . . . .  225
        15.1.  Procedure 0: CB_NULL - No Operation . . . . . . . .  225
        15.2.  Procedure 1: CB_COMPOUND - Compound
               Operations. . . . . . . . . . . . . . . . . . . . .  226

Top      ToC       Page 7 
               15.2.1.  Operation 3: CB_GETATTR - Get
                        Attributes . . . . . . . . . . . . . . . .  228
               15.2.2.  Operation 4: CB_RECALL -
                        Recall an Open Delegation. . . . . . . . .  229
               15.2.3.  Operation 10044: CB_ILLEGAL -
                        Illegal Callback Operation . . . . . . . .  230
   16.  Security Considerations  . . . . . . . . . . . . . . . . .  231
   17.  IANA Considerations  . . . . . . . . . . . . . . . . . . .  232
        17.1.  Named Attribute Definition. . . . . . . . . . . . .  232
        17.2.  ONC RPC Network Identifiers (netids). . . . . . . .  232
   18.  RPC definition file  . . . . . . . . . . . . . . . . . . .  234
   19.  Acknowledgements . . . . . . . . . . . . . . . . . . . . .  268
   20.  Normative References . . . . . . . . . . . . . . . . . . .  268
   21.  Informative References . . . . . . . . . . . . . . . . . .  270
   22.  Authors' Information . . . . . . . . . . . . . . . . . . .  273
        22.1.  Editor's Address. . . . . . . . . . . . . . . . . .  273
        22.2.  Authors' Addresses. . . . . . . . . . . . . . . . .  274
   23.  Full Copyright Statement . . . . . . . . . . . . . . . . .  275

Top      ToC       Page 8 
1.  Introduction

1.1.  Changes since RFC 3010

   This definition of the NFS version 4 protocol replaces or obsoletes
   the definition present in [RFC3010].  While portions of the two
   documents have remained the same, there have been substantive changes
   in others.  The changes made between [RFC3010] and this document
   represent implementation experience and further review of the
   protocol.  While some modifications were made for ease of
   implementation or clarification, most updates represent errors or
   situations where the [RFC3010] definition were untenable.

   The following list is not all 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  Clarifications and error conditions were added 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  Clarifications for the ACL and mode attributes to address
      evaluation and partial support.

   o  For identifiers that are defined as XDR opaque, limits were set on
      their size.

   o  Added the mounted_on_filed 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 LOCKOWNER_RELEASE to enable notifying the
      server that a lock_owner4 will no longer be used by the client.

   o  RENEW operation changes to identify the client correctly and allow
      for additional error returns.

Top      ToC       Page 9 
   o  Verify error return possibilities for all operations.

   o  Remove use of the pathname4 data type from LOOKUP and OPEN in
      favor of having the client construct a sequence of LOOKUP
      operations to achieive the same effect.

   o  Clarification of the internationalization issues and adoption of
      the new stringprep profile framework.

1.2.  NFS Version 4 Goals

   The NFS version 4 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
   filesystems, simplicity, and good performance.  The NFS version 4
   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 ONCRPC working group in
      supporting the RPCSEC_GSS protocol.  Additionally, the NFS version
      4 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 filesystem model that provides a useful,
      common set of features that does not unduly favor one filesystem
      or operating system over another.

   o  Designed for protocol extensions.

      The protocol is designed to accept standard extensions that do not
      compromise backward compatibility.

1.3.  Inconsistencies of this Document with Section 18

   Section 18, RPC Definition File, contains the definitions in XDR
   description language of the constructs used by the protocol.  Prior
   to Section 18, several of the constructs are reproduced for purposes

Top      ToC       Page 10 
   of explanation.  The reader is warned of the possibility of errors in
   the reproduced constructs outside of Section 18.  For any part of the
   document that is inconsistent with Section 18, Section 18 is to be
   considered authoritative.

1.4.  Overview of NFS version 4 Features

   To provide a reasonable context for the reader, the major features of
   NFS version 4 protocol will be reviewed in brief.  This will be done
   to provide an appropriate context for both the reader who is familiar
   with the previous versions of the NFS protocol and the reader that is
   new to the NFS protocols.  For the reader new to the NFS protocols,
   there is still a fundamental knowledge that is expected.  The reader
   should be familiar with the XDR and RPC protocols as described in
   [RFC1831] and [RFC1832].  A basic knowledge of filesystems and
   distributed filesystems is expected as well.

1.4.1.  RPC and Security

   As with previous versions of NFS, the External Data Representation
   (XDR) and Remote Procedure Call (RPC) mechanisms used for the NFS
   version 4 protocol are those defined in [RFC1831] and [RFC1832].  To
   meet end to end security requirements, the RPCSEC_GSS framework
   [RFC2203] 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 NFS version 4 protocol.
   Kerberos V5 will be used as described in [RFC1964] to provide one
   security framework.  The LIPKEY GSS-API mechanism described in
   [RFC2847] will be used to provide for the use of user password and
   server public key by the NFS version 4 protocol.  With the use of
   RPCSEC_GSS, other mechanisms may also be specified and used for NFS
   version 4 security.

   To enable in-band security negotiation, the NFS version 4 protocol
   has added a new operation which provides the client a method of
   querying the server about its policies regarding which security
   mechanisms must be used for access to the server's filesystem
   resources.  With this, the client can securely match the security
   mechanism that meets the policies specified at both the client and
   server.

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 NFS
   version 4 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.

Top      ToC       Page 11 
   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 filesystem
   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 NFS version 4 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 "saved filehandle".  Most operations use the
   "current filehandle" as the filesystem 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.  Filesystem Model

   The general filesystem model used for the NFS version 4 protocol is
   the same as previous versions.  The server filesystem 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 NFS version 4 protocol does not require a separate protocol to
   provide for the initial mapping between path name 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 filesystem tree provided by the server.  The server
   provides multiple filesystems by gluing them together with pseudo
   filesystems.  These pseudo filesystems provide for potential gaps in
   the path names between real filesystems.

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 filesystem object to which it referred.  For some server
   implementations, this persistence requirement has been difficult to

Top      ToC       Page 12 
   meet.  For the NFS version 4 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 filesystem 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 NFS version 4 protocol introduces three classes of filesystem or
   file attributes.  Like the additional filehandle type, the
   classification of file attributes has been done to ease server
   implementations along with extending the overall functionality of the
   NFS protocol.  This attribute model is structured to be extensible
   such that new attributes can be introduced in minor revisions of the
   protocol without requiring significant rework.

   The three classifications are: mandatory, recommended and named
   attributes.  This is a significant departure from the previous
   attribute model used in the NFS protocol.  Previously, the attributes
   for the filesystem and file objects were a fixed set of mainly UNIX
   attributes.  If the server or client did not support a particular
   attribute, it would have to simulate the attribute the best it could.

   Mandatory attributes are the minimal set of file or filesystem
   attributes that must be provided by the server and must be properly
   represented by the server.  Recommended attributes represent
   different filesystem types and operating environments.  The
   recommended attributes will allow for better interoperability and the
   inclusion of more operating environments.  The mandatory and
   recommended attribute sets are traditional file or filesystem
   attributes.  The third type of attribute is the named attribute.  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.

   One significant addition to the recommended set of file attributes is
   the Access Control List (ACL) attribute.  This attribute provides for
   directory and file access control beyond the model used in previous
   versions of the NFS protocol.  The ACL definition allows for
   specification of user and group level access control.

Top      ToC       Page 13 
1.4.3.3.  Filesystem Replication and Migration

   With the use of a special file attribute, the ability to migrate or
   replicate server filesystems is enabled within the protocol.  The
   filesystem locations attribute provides a method for the client to
   probe the server about the location of a filesystem.  In the event of
   a migration of a filesystem, the client will receive an error when
   operating on the filesystem and it can then query as to the new file
   system location.  Similar steps are used for replication, the client
   is able to query the server for the multiple available locations of a
   particular filesystem.  From this information, the client can use its
   own policies to access the appropriate filesystem location.

1.4.4.  OPEN and CLOSE

   The NFS version 4 protocol introduces OPEN and CLOSE operations.  The
   OPEN operation provides a single point where file lookup, creation,
   and share semantics can be combined.  The CLOSE operation also
   provides for the release of state accumulated by OPEN.

1.4.5.  File locking

   With the NFS version 4 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).  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 a NFS
   client.  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 with 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 NFS version 4
   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 filesystem 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 kept or released.  Also, when the
   file is closed, any modified data is written to the server.

Top      ToC       Page 14 
   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 NFS version 4 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 or write delegation for the file.
   If the client is granted a 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 a 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 can not be granted.  The essence of a
   delegation is that it allows the client to locally service operations
   such as OPEN, CLOSE, LOCK, LOCKU, READ, WRITE without immediate
   interaction with the server.

1.5.  General Definitions

   The following definitions are provided for the purpose of providing
   an appropriate context for the reader.


   Client    The "client" is the entity that accesses the NFS server's
             resources.  The client may be an application which contains
             the logic to access the NFS server directly.  The client
             may also be the traditional operating system client remote
             filesystem services for a set of applications.

             In the case of file locking the client is 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
             multiple clients may exist on the same network node.

   Clientid  A 64-bit quantity used as a unique, short-hand reference to
             a client supplied Verifier and ID.  The server is
             responsible for supplying the Clientid.

Top      ToC       Page 15 
   Lease     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
             interval.  Note that the fixed interval was chosen to
             alleviate the expense a server would have in maintaining
             state about variable length leases across server failures.

   Lock      The term "lock" is used to refer to both record (byte-
             range) locks as well as share reservations unless
             specifically stated otherwise.

   Server    The "Server" is the entity responsible for coordinating
             client access to a set of filesystems.

   Stable Storage
             NFS version 4 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, nonvolatile 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 uninterruptible power system (UPS) and
                recovery software.

   Stateid   A 128-bit quantity returned by a server that uniquely
             defines the open and locking state provided by the server
             for a specific open or lock owner for a specific file.

Top      ToC       Page 16 
             Stateids composed of all bits 0 or all bits 1 have special
             meaning and are reserved values.

   Verifier  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.



(page 16 continued on part 2)

Next RFC Part