idnits 2.17.1 draft-shepler-nfsv4-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-25) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://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. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 446 has weird spacing: '...blksize bloc...' == Line 447 has weird spacing: '..._blocks blo...' == Line 3359 has weird spacing: '...ttrlist att...' == Line 3695 has weird spacing: '...D4resok resok...' -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (August 1998) is 9385 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Missing reference section? 'RFC1094' on line 4060 looks like a reference -- Missing reference section? 'RFC1813' on line 4066 looks like a reference -- Missing reference section? 'RFC1831' on line 4072 looks like a reference -- Missing reference section? 'RFC1832' on line 4078 looks like a reference -- Missing reference section? 'RFC2203' on line 4098 looks like a reference -- Missing reference section? 'RFC1833' on line 4084 looks like a reference -- Missing reference section? 'RFC2078' on line 4090 looks like a reference -- Missing reference section? 'SPNEGO' on line 4112 looks like a reference -- Missing reference section? 'RFC 2078' on line 2979 looks like a reference -- Missing reference section? 'Gray' on line 4013 looks like a reference -- Missing reference section? 'Juszczak' on line 4018 looks like a reference -- Missing reference section? 'Kazar' on line 4027 looks like a reference -- Missing reference section? 'Macklem' on line 4034 looks like a reference -- Missing reference section? 'Mogul' on line 4125 looks like a reference -- Missing reference section? 'Nowicki' on line 4047 looks like a reference -- Missing reference section? 'Pawlowski' on line 4054 looks like a reference -- Missing reference section? 'Sandberg' on line 4104 looks like a reference -- Missing reference section? 'Srinivasan' on line 4118 looks like a reference Summary: 8 errors (**), 0 flaws (~~), 5 warnings (==), 21 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group S. Shepler 3 Internet Draft August 1998 4 Document: draft-shepler-nfsv4-02.txt 6 NFS version 4 Strawman 8 Status of this Memo 10 This document is an Internet-Draft. Internet-Drafts are working 11 documents of the Internet Engineering Task Force (IETF), its areas, 12 and its working groups. Note that other groups may also distribute 13 working documents as Internet-Drafts. 15 Internet-Drafts are draft documents valid for a maximum of six months 16 and may be updated, replaced, or obsoleted by other documents at any 17 time. It is inappropriate to use Internet- Drafts as reference 18 material or to cite them other than as "work in progress." 20 To view the entire list of current Internet-Drafts, please check the 21 "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow 22 Directories on ftp.is.co.za (Africa), ftp.nordu.net (Northern 23 Europe), ftp.nis.garr.it (Southern Europe), munnari.oz.au (Pacific 24 Rim), ftp.ietf.org (US East Coast), or ftp.isi.edu (US West Coast). 26 Abstract 28 NFS version 4 is meant to be a further revision of the NFS protocol 29 defined already by versions 2 and 3. It retains the essential 30 characteristics of previous versions: stateless design for easy 31 recovery, independent of transport protocols, operating systems and 32 filesystems, simplicity, and good performance. 34 This strawman is being offered as a starting point for future 35 discussions and work on NFS version 4. The document contains ideas 36 presented and discussed via email at nfsv4-wg@sunroof.eng.sun.com. 37 Additional content has been added in areas with the intent of 38 offering more suggestions for future discussion. 40 Goals for NFS version 4 include: strong security, access and good 41 performance via the Internet, cross-platform interoperability, and 42 protocol extensibility. 44 Strawman NFS version 4 August 1998 46 Table of Contents 48 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 49 2. RPC and Security Flavor . . . . . . . . . . . . . . . . . . 5 50 2.1. Ports and Transports . . . . . . . . . . . . . . . . . . . 5 51 2.2. Security Flavors . . . . . . . . . . . . . . . . . . . . . 5 52 2.2.1. Security mechanisms for NFS version 4 . . . . . . . . . 5 53 2.3. Security Negotiation . . . . . . . . . . . . . . . . . . . 6 54 2.3.1. Security Error . . . . . . . . . . . . . . . . . . . . . 6 55 2.3.2. SECINFO . . . . . . . . . . . . . . . . . . . . . . . . 6 56 2.4. Alternate Negotiation Technique - SPNEGO . . . . . . . . . 6 57 3. File handles . . . . . . . . . . . . . . . . . . . . . . . . 7 58 3.1. Obtaining the first file handle . . . . . . . . . . . . . 7 59 3.2. The persistent and volatile file handle . . . . . . . . . 7 60 4. Basic Data Types . . . . . . . . . . . . . . . . . . . . . . 9 61 5. File Attributes . . . . . . . . . . . . . . . . . . . . . 11 62 5.1. Defining Attributes . . . . . . . . . . . . . . . . . . 12 63 5.2. File Attribute Bits . . . . . . . . . . . . . . . . . . 12 64 6. Defined Error Numbers . . . . . . . . . . . . . . . . . . 20 65 7. Compound Requests . . . . . . . . . . . . . . . . . . . . 24 66 8. NFS Version 4 Requests . . . . . . . . . . . . . . . . . . 25 67 8.1. Evaluation of a Compound Request . . . . . . . . . . . . 25 68 9. NFS Version 4 Procedures . . . . . . . . . . . . . . . . . 26 69 9.1. Procedure 0: NULL - No operation . . . . . . . . . . . . 27 70 9.2. Procedure 1: ACCESS - Check Access Permission . . . . . 28 71 9.3. Procedure 2: COMMIT - Commit cached data . . . . . . . . 31 72 9.4. Procedure 3: CREATE - Create a filesystem object . . . . 34 73 9.5. Procedure 4: GETATTR - Get attributes . . . . . . . . . 38 74 9.6. Procedure 5: GETFH - Get current filehandle . . . . . . 39 75 9.7. Procedure 6: LINK - Create link to an object . . . . . . 40 76 9.8. Procedure 7: LOCKR - Create a read lock . . . . . . . . 42 77 9.9. Procedure 8: LOCKW - Create write lock . . . . . . . . . 44 78 9.10. Procedure 9: LOCKT - test for lock . . . . . . . . . . 46 79 9.11. Procedure 10: LOCKX - validate and extend lock . . . . 47 80 9.12. Procedure 11: LOCKU - Unlock file . . . . . . . . . . . 49 81 9.13. Procedure 12: LOOKUP - Lookup filename . . . . . . . . 50 82 9.14. Procedure 13: LOOKUPP - Lookup parent directory . . . . 52 83 9.15. Procedure 14: NVERIFY - Verify attributes different . . 53 84 9.16. Procedure 15: RESTOREFH - Restore saved filehandle . . 54 85 9.17. Procedure 16: SAVEFH - Save current filehandle . . . . 55 86 9.18. Procedure 17: PUTFH - Set current filehandle . . . . . 56 87 9.19. Procedure 18: PUTROOTFH - Set root filehandle . . . . . 57 88 9.20. Procedure 19: READ - Read from file . . . . . . . . . . 58 89 9.21. Procedure 20: READDIR - Read directory . . . . . . . . 60 90 9.22. Procedure 21: READLINK - Read symbolic link . . . . . . 63 91 9.23. Procedure 22: REMOVE - Remove filesystem object . . . . 65 92 9.24. Procedure 23: RENAME - Rename directory entry . . . . . 67 93 9.25. Procedure 24: SETATTR - Set attributes . . . . . . . . 69 95 Strawman NFS version 4 August 1998 97 9.26. Procedure 25: VERIFY - Verify attributes same . . . . . 71 98 9.27. Procedure 26: WRITE - Write to file . . . . . . . . . . 72 99 9.28. Procedure 27: SECINFO - Obtain Available Security . . . 76 100 10. Locking notes . . . . . . . . . . . . . . . . . . . . . . 78 101 10.1. Short and long leases . . . . . . . . . . . . . . . . . 78 102 10.2. Clocks and leases . . . . . . . . . . . . . . . . . . . 78 103 10.3. Locks and lease times . . . . . . . . . . . . . . . . . 79 104 10.4. Lease scalability . . . . . . . . . . . . . . . . . . . 79 105 10.5. Rejecting write locks and denial of service . . . . . . 79 106 10.6. Locking of directories and other meta-files . . . . . . 79 107 10.7. Proxy servers and leases . . . . . . . . . . . . . . . 79 108 10.8. Archive updates and lease time adjustment . . . . . . . 79 109 10.9. Locking and the new latency . . . . . . . . . . . . . . 80 110 11. NFS Version 4 RPC definition file . . . . . . . . . . . . 81 111 12. Bibliography . . . . . . . . . . . . . . . . . . . . . . 99 112 13. Author's Address . . . . . . . . . . . . . . . . . . . . 102 114 Strawman NFS version 4 August 1998 116 1. Introduction 118 NFS version 4 is a further revision of the NFS protocol defined 119 already by versions 2 [RFC1094] and 3 [RFC1813]. It retains the 120 essential characteristics of previous versions: stateless design for 121 easy recovery, independent of transport protocols, operating systems 122 and filesystems, simplicity, and good performance. The NFS version 4 123 revision has the following goals: 125 o Improved access and good performance on the Internet. 127 The protocol is designed to transit firewalls easily, perform 128 well where latency is high and bandwidth is low, and scale to 129 very large numbers of clients per server. 131 o Strong security with negotiation built into the protocol. 133 The protocol builds on the work of the ONCRPC working group in 134 supporting the RPCSEC_GSS protocol. Additionally NFS version 4 135 provides a mechanism to allow clients and servers to negotiate 136 security and require clients and servers to support a minimal 137 set of security schemes. 139 o Good cross-platform interoperability. 141 The protocol features a filesystem model that provides a useful, 142 common set of features that does not unduly favor one filesystem 143 or operating system over another. 145 o Designed for protocol extensions. 147 The protocol is designed to accept standard extensions that do 148 not compromise backward compatibility. 150 Strawman NFS version 4 August 1998 152 2. RPC and Security Flavor 154 The NFS version 4 protocol will use the Remote Procedure Call (RPC) 155 version 2 and corresponding eXternal Data Representation (XDR) as 156 defined in [RFC1831] and [RFC1832]. The RPCSEC_GSS security flavor 157 as defined in [RFC2203] will be used as the mechanism to deliver 158 stronger security to NFS version 4. 160 2.1. Ports and Transports 162 Historically, NFS version 2 and version 3 servers have resided on 163 UDP/TCP port 2049. Port 2049 is a IANA registered port number for NFS 164 and therefore will continue to be used for NFS version 4. The NFS 165 server should use port 2049 as a means to ease the use of NFS through 166 firewalls. This means that for NFS version 4 services the client 167 will not need to use the RPC binding protocols as described in 168 [RFC1833]. 170 The NFS server, at a minimum, must offer its RPC service via the TCP 171 transport. The use of UDP for RPC service offering should also be 172 present if applicable. The NFS client should have a preference for 173 TCP usage but should supply a mechanism to override TCP in favor of 174 UDP as the RPC transport. 176 2.2. Security Flavors 178 Traditional RPC implementations have included AUTH_NONE, AUTH_SYS, 179 AUTH_DH, and AUTH_KRB4 as security flavors. With [RFC2203] an 180 additional security flavor of RPCSEC_GSS has been introduced which 181 uses the functionality of GSS_API [RFC2078]. This allows for the use 182 of varying security mechanisms by the RPC layer without the 183 additional implementation overhead of adding RPC security flavors. 185 2.2.1. Security mechanisms for NFS version 4 187 As a goal of the NFS version 4 work, adding stronger security to the 188 protocol definition is required. The use of RPCSEC_GSS will require 189 selection of: mechanism, quality of protection, and service 190 (authentication, integrity, privacy). The remainder of this document 191 will refer to these three parameters of the RPCSEC_GSS security as 192 the security triple. 194 NOTE: Kerberos-V5 has been suggested as one of the security 195 mechanisms. Another mechanism should be chosen and should 196 be a public key based system so as to complement the 197 Kerberos-V5 selection. 199 Strawman NFS version 4 August 1998 201 2.3. Security Negotiation 203 With the NFS version 4 server potentially offering multiple security 204 mechanisms, the client will need a way to determine or negotiate 205 which mechanism is to be used for its communication with the server. 206 The NFS server may have multiple points within its file system name 207 space that are available for use by NFS clients. In turn the NFS 208 server may be configured such that each of these entry points may 209 have different or multiple security mechanisms in use. 211 The security negotiation between client and server must be done with 212 a secure channel to eliminate the possibility of a third party 213 intercepting the negotiation sequence and forcing the client and 214 server to choose a lower level of security than required/desired. 216 2.3.1. Security Error 218 Based on the assumption that each NFS version 4 client and server 219 must support a minimum set of security (i.e. Kerberos-V5 under 220 RPCSEC_GSS, ), the NFS client will start its 221 communication with the server with one of the minimal security 222 triples. During communication with the server, the client may 223 receive an NFS error of NFS4ERR_WRONGSEC. This error allows the 224 server to notify the client that the security triple currently being 225 used is not appropriate for access to the server's file system 226 resources. The client is then responsible for determining what 227 security triples are available at the server and choose one which is 228 appropriate for the client. 230 2.3.2. SECINFO 232 The new procedure SECINFO (see SECINFO procedure definition) will 233 allow the client to determine, on a per filehandle basis, what 234 security triple is to be used for server access. In general, the 235 client will not have to use the SECINFO procedure except during 236 initial communication with the server or when the client crosses 237 policy boundaries at the server. It could happen that the server's 238 policies change during the client's interaction therefore forcing the 239 client to negotiate a new security triple. 241 2.4. Alternate Negotiation Technique - SPNEGO 243 It has also been suggested that the SPNEGO protocol defined in 244 [SPNEGO] would also be available for use with RPCSEC_GSS. However, 245 this seems to imply that the NFS server would need to offer all of 246 its resources under the same security mechanism. This needs to be 247 evaluated further as an alternative. 249 Strawman NFS version 4 August 1998 251 3. File handles 253 The file handle in the NFS protocol is an opaque identifier for a 254 file system object. The server is responsible for translating the 255 file handle to its internal representation of the file system object. 256 The file handle is uniquely identifies a file system object at the 257 NFS server. The client should be able to depend on the fact that a 258 file handle will not be reused once a file system object has been 259 destroyed. If the file handle is reused, the time elapsed before 260 reuse will be very significant. Note that each NFS procedure is 261 defined in terms of its file handle(s) except for the NULL procedure. 263 3.1. Obtaining the first file handle 265 If each of the meaningful operations of the NFS protocol require a 266 file handle, the client must have a mechanism to obtain the first 267 file handle. With NFS version 2 [RFC1094] and NFS version 3 268 [RFC1813], there exists an ancillary, protocol to obtain the first 269 file handle. The MOUNT protocol, RPC program number 100005, provides 270 the mechanism of translating a string based file system path name to 271 a file handle which can then be used by the NFS protocols. 273 The MOUNT protocol as currently implemented has deficiencies in the 274 area of security and use via firewalls. This is one reason that the 275 use of the public file handle was introduced [add references to RFCs 276 for WebNFS]. The public file handle is a special case file handle 277 that is used in combination with a path name to avoid using the MOUNT 278 protocol for obtaining the first file handle. With the introduction 279 and use of the public file handle in the previous versions of NFS, it 280 has been shown that the MOUNT protocol is unnecessary for viable 281 interaction between the client and server with the use of file 282 handles. 284 3.2. The persistent and volatile file handle 286 For the first time in NFS version 4, the file handle constructed by 287 the server can be volatile. In the previous versions of NFS, the 288 server was responsible for ensuring the persistence of the file 289 handle. This meant that as long as a file system object remained in 290 existence at the server the file handle for that object had to be the 291 same each time the client asked for it. This persistent quality 292 eased the implementation at the client in the event of server restart 293 or failure and recovery. For some servers, fulfilling the persistent 294 requirement has been straight forward; for others it has been 295 difficult and affected at best performance and at worst correctness. 297 The existence of the volatile file handle requires the client to 298 implement a method of recovering from the expiration of a file 300 Strawman NFS version 4 August 1998 302 handle. Most commonly the client will need to store the component 303 names associated with the file system object in question. With these 304 names, the client will be able to recover by finding a file handle in 305 the name space that is still available or by starting at the root of 306 the server's file system name space. 308 The use of a volatile file handle provides these advantages: 310 o Allows or eases the server implementation requirements 312 o Server can provide extended services more easily with the use of 313 volatile file handles (HSM software, file system reorganization) 315 o Others??? 317 NOTE: Need to describe a method of identifying a file 318 handle as persistent or volatile (In the file handle 319 itself?). Also need a discussion of when and where a each 320 type of file handle would be used. Also need to extend the 321 list of examples of what things volatile file handles 322 enable (or remove the list altogether). 324 Note: A question has arisen about the server's ability to 325 return a correct error code (NFS4ERR_STALE vs. 326 NFS4ERR_EXPIRED). One implementation that has been 327 suggested is the following. A volatile file handle, while 328 opaque to the client could contain: 330 volatile bit = 1 | server boot time | slot | generation 331 number 333 slot is an index in the server volatile file handle table. 334 generation number is the generation number for the table 335 entry/slot. If the server boot time is less than the 336 current server boot time, return NFS4ERR_EXPIRED. If slot 337 is out of range, return NFS4ERR_EXPIRED. If the generation 338 number does not match, return NFS4ERR_EXPIRED. 340 When the server reboots, the table is gone (it is 341 volatile). 343 If volatile bit is 0, then it is a persistent file handle 344 with a different structure following it. 346 Strawman NFS version 4 August 1998 348 4. Basic Data Types 350 Arguments and results from operations will be described in terms of 351 basic XDR types defined in [RFC1832]. The following data types will 352 be defined in terms of basic XDR types: 354 filehandle: opaque <128> 356 An NFS version 4 filehandle. A filehandle with zero length is 357 recognized as a "public" filehandle. 359 utf8string: opaque <> 361 A counted array of octets that contains a UTF-8 string. 363 bitmap: uint32 <> 365 A counted array of 32 bit integers used to contain bit values. 366 The position of the integer in the array that contains bit n can 367 be computed from the expression (n / 32) and its bit within that 368 integer is (n mod 32). 370 0 1 371 +-----------+-----------+-----------+-- 372 | count | 31 .. 0 | 63 .. 32 | 373 +-----------+-----------+-----------+-- 375 createverf: opaque<8> 377 Verify used for exclusive create semantics 379 nfstime4 380 struct nfstime4 { 381 int64_t seconds; 382 uint32_t nseconds; 383 } 385 The nfstime4 structure gives the number of seconds and 386 nanoseconds since midnight or 0 hour January 1, 1970 Coordinated 387 Universal Time (UTC). Values greater than zero for the seconds 388 field denote dates after the 0 hour January 1, 1970. Values 389 less than zero for the seconds field denote dates before the 0 390 hour January 1, 1970. In both cases, the nseconds field is to 391 be added to the seconds field for the final time representation. 392 For example, if the time to be represented is one-half second 393 before 0 hour January 1, 1970, the seconds field would have a 394 value of negative one (-1) and the nseconds fields would have a 395 value of one-half second (500000000). Values greater than 397 Strawman NFS version 4 August 1998 399 999,999,999 for nseconds are considered invalid. 401 This data type is used to pass time and date information. A 402 server converts to and from local time when processing time 403 values, preserving as much accuracy as possible. If the 404 precision of timestamps stored for a file system object is less 405 than defined, loss of precision can occur. An adjunct time 406 maintenance protocol is recommended to reduce client and server 407 time skew. 409 specdata4 410 struct specdata4 { 411 uint32_t specdata1; 412 uint32_t specdata2; 413 } 415 This data type represents additional information for the device 416 file types NFCHR and NFBLK. 418 Note: This is used for the rdev attribute. Is this the 419 correct representation or should this be considered an 420 extended/named attribute for a file. Is there some other 421 solution? 423 Strawman NFS version 4 August 1998 425 5. File Attributes 427 Previous versions of the NFS protocol supported only the set of POSIX 428 file attributes. 430 Posix V2 Fattr V3 Fattr3 431 ----- -------- --------- 433 - type type 434 st_mode mode mode 435 st_ino fileid fileid 436 st_dev fsid fsid 437 st_rdev rdev rdev 438 st_nlink nlink nlink 439 st_uid uid uid 440 st_gid gid gid 441 st_size size size 442 - - used 443 st_atime atime atime 444 st_mtime mtime mtime 445 st_ctime ctime ctime 446 st_blksize blocks - 447 st_blocks blocksize - 449 This fixed set of attributes has been limiting: 451 o There is no way to add new attributes without revising the 452 protocol. This penalizes file systems and/or operating systems 453 that support attributes that do not map into the POSIX set. 455 o Not all file systems or operating systems support the full range 456 of POSIX attributes. The server is required to "invent" 457 approximate values for attributes that it does not support. The 458 client does not know that the server doesn't support these 459 values. 461 o Attributes cannot be obtained individually. If the client needs 462 to obtain only one attribute it must request them all. Some of 463 those attributes may be computationally expensive for the server 464 to return. 466 o The set of supported attributes may vary depending on the type 467 of file system object. Additionally, previous versions of the 468 protocol required multiple attribute spaces for files (GETATTR) 470 Strawman NFS version 4 August 1998 472 and file systems (FSINFO, FSSTAT, PATHCONF) which heavily 473 favored POSIX-based file systems. 475 To overcome these limitations NFS version 4 supports an attribute 476 model with the following features: 478 o Extensibility. New attributes can be added in incremental 479 revisions of the protocol. 481 o For each file system object the client can determine which 482 attributes are supported. 484 o The client can select the attributes it needs. 486 5.1. Defining Attributes 488 Each attribute is assigned a unique integer which corresponds to a 489 position in a bitmap. When requesting or setting attributes the 490 client sets the appropriate bits in the bitmap to identify the 491 attributes. Similarly, when returning attributes the server returns 492 a bitmap that identifies the attributes returned. The sequence of 493 attributes in a request or reply must follow the 495 5.2. File Attribute Bits 497 Name: type 499 Data type: uint32 501 Description: Type of file. 503 Note: Some of these are now handled by accessbits. Need to 504 represent Unix perm bits as an ACL 506 Name: mode 508 Data type: uint32 510 Description: Protection mode bits 512 The mode bits are defined as follows: 514 Strawman NFS version 4 August 1998 516 0x00800 Set user ID on execution. 517 0x00400 Set group ID on execution. 518 0x00200 Save swapped text (not defined in POSIX). 519 0x00100 Read permission for owner. 520 0x00080 Write permission for owner. 521 0x00040 Execute permission for owner on a file. 522 Or lookup (search) permission for owner 523 in directory. 524 0x00020 Read permission for group. 525 0x00010 Write permission for group. 526 0x00008 Execute permission for group on a file. 527 Or lookup (search) permission for group 528 in directory. 529 0x00004 Read permission for others. 530 0x00002 Write permission for others. 531 0x00001 Execute permission for others on a file. 532 Or lookup (search) permission for others 533 in directory. 535 Name: accessbits 537 Data type: uint32 539 Description: 541 0x0001 READ. 542 Read data from file or read a directory. 543 0x0002 LOOKUP. 544 Look up a name in a directory (no meaning 545 for non-directory objects). 547 0x0004 MODIFY. 548 Rewrite existing file data or modify 549 existing directory entries. 551 0x0008 EXTEND. 552 Write new data or add directory entries. 554 0x0010 DELETE. 555 Delete an existing directory entry. 557 0x0020 EXECUTE. 559 Strawman NFS version 4 August 1998 561 Execute file (no meaning for a directory). 563 Name: nlink 565 Data type: uint32 567 Description: Number of hard links to the file - that is, the number 568 of different names for the same file. If a 569 modification is made to data within a file and the file 570 has a nlink value greater than 1, then the 571 modifications will appear under each of the names for 572 the file. 574 Name: uid 576 Data type: utf8string 578 Description: Identifier of the owner of the file. 580 Name: gid 582 Data type: utf8string 584 Description: Identifier of the group of the file. 586 NOTE: The string representation for the user and group 587 identifiers of a file are provided to include support for 588 user identifiers beyond the scope of the traditional Unix 589 uid/gid name space. The contents of the user and group 590 identifier should be defined or have strong 591 recommendations. One suggestion for user identifier might 592 be user@domain. To translate a traditional Unix uid the 593 representation may be something like 123456@uid. 595 Name: size 597 Data type: uint64 599 Description: Size of the file in bytes. 601 Strawman NFS version 4 August 1998 603 Name: used 605 Data type: uint64 607 Description: Number of bytes of disk space that the file actually 608 uses (which can be smaller because the file may have 609 holes or it may be larger due to fragmentation). 611 Name: rdev 613 Data type: specdata4 615 Description: Describes the device file if the file type is NF4CHR or 616 NF4BLK. For all other file types, this attribute is 617 undefined. If this attribute is returned from the 618 server for file types other than NF4CHR and NF4BLK, the 619 client should consider the values to be zero. 621 Name: fsid 623 Data type: uint64 625 Description: The file system identifier for the file system. This 626 identifier is expected to uniquely identify the file 627 system at the server. 629 NOTE: The unique quality of the fsid will indicate to the 630 client that certain operations will fail if the source and 631 target of the operation are located on different fsids. A 632 RENAME is a good example of this. If the source and 633 destination directories have different fsid values at the 634 server then the RENAME operation will fail. This type of 635 failure mode needs to be determined and documented for all 636 procedures. 638 Name: fileid 640 Data type: uint32 642 Description: A number which uniquely identifies the file within the 643 file system. On UNIX this would be the inode number. 645 Strawman NFS version 4 August 1998 647 Note: Are the fsid and fileid data types large enough for 648 unique identifiers? Are there environments that something 649 more is needed. 651 Name: atime 653 Data type: nfstime4 655 Description: The time when the file data was last accessed. 657 Name: mtime 659 Data type: nfstime4 661 Description: The time when the file data was last modified. 663 Note: In the case that a file is updated twice within the 664 granularity of the server's mtime, what is the server 665 supposed to do? Is it supposed to increase the mtime 666 nseconds field to signify that a change has occurred? In 667 the case that mtime is not kept for certain file system 668 objects, what is the server supposed to do with the object 669 is updated? Is mtime sufficient or should there be another 670 opaque attribute that can be used by the server to fulfill 671 the client's need to know if the file system object has 672 been updated. 674 Name: ctime 676 Data type: nfstime4 678 Description: The time when the attributes of the file were last 679 changed. Writing to the file changes the ctime in 680 addition to the mtime. 682 Name: rtmax 684 Data type: uint32 686 Strawman NFS version 4 August 1998 688 Description: The maximum size in bytes of a READ request supported 689 by the server. Any READ with a number greater than 690 rtmax will result in a short read of rtmax bytes or 691 less. 693 Name: wtmax 695 Data type: uint32 697 Description: The maximum size of a WRITE request supported by the 698 server. In general, the client is limited by wtmax 699 since there is no guarantee that a server can handle a 700 larger write. Any WRITE with a count greater than wtmax 701 will result in a short write of at most wtmax bytes. 703 Name: maxfilesize 705 Data type: uint64 707 Description: The maximum size of a file on the file system. 709 Name: time_delta 711 Data type: nfstime4 713 Description: The server time granularity. When setting a file time 714 using SETATTR, the server guarantees only to preserve 715 times to this accuracy. If this is {0, 1}, the server 716 can support nanosecond times, {0, 1000000} denotes 717 millisecond precision, and {1, 0} indicates that times 718 are accurate only to the nearest second. 720 Note: Should there be more granularity definitions or a 721 general scheme devised for this? Is this attribute 722 necessary at all? If there are mechanisms to ensure that 723 modification times are recorded correctly or at least 724 recorded in such a way to signify that a modification has 725 occurred, is this attribute needed? 727 Strawman NFS version 4 August 1998 729 Name: linkmax 731 Data type: uint32 733 Description: The maximum number of hard links to an object. 735 Name: name_max 737 Data type: uint32 739 Description: The maximum length of a component of a filename. 741 Name: change 743 Data type: uint64 745 Description: A value created by the server that the client can use 746 to determine if a file data, directory contents or 747 attributes have been modified. The server can just 748 return the file mtime in this field though if a more 749 precise value exists then it can be substituted, for 750 instance, a checksum or sequence number. 752 Name: properties 754 Data type: uint32 756 Description: A bit mask of file system properties. The following 757 values are defined: 759 FSF_LINK If this bit is 1 (TRUE), the file system 760 supports hard links. 761 FSF_SYMLINK If this bit is 1 (TRUE), the file system 762 supports symbolic links. 763 FSF_HOMOGENEOUS If this bit is 1 (TRUE), the information 764 in the properties attributes is identical for 765 every file and directory in the file 766 system. If it is 0 (FALSE), the client 767 should retrieve properties information for 768 each file and directory as required. 770 Strawman NFS version 4 August 1998 772 FSF_CANSETTIME If this bit is 1 (TRUE), the server will 773 set the times for a file via SETATTR if 774 requested (to the accuracy indicated by 775 time_delta). If it is 0 (FALSE), the 776 server cannot set times as requested. 777 FSF_NOTRUNC If this bit is 1 (TRUE), the server will 778 reject any request that includes a name longer 779 than name_max with the error, 780 NFS4ERR_NAMETOOLONG. If FALSE, any length 781 name over name_max bytes will be silently 782 truncated to name_max bytes. 783 FSF_CHOWN_RESTRICTED If this bit is 1 (TRUE), the server 784 will reject any request to change either the 785 owner or the group associated with a file if 786 the caller is not the privileged user. (UID 0) 787 FSF_CASE_INSENSITIVE If this bit is 1 (TRUE), the server 788 file system does not distinguish case when 789 interpreting filenames. 790 FSF_CASE_PRESERVING If this bit is 1 (TRUE), the server 791 will preserve the case of a name during the 792 creation of a file system object. 793 (i.e. CREATE, MKDIR, MKNOD, SYMLINK, RENAME 794 or LINK operation) 796 For FSF_CHOWN_RESTRICTED, what should be done with the 797 privileged user definition in face of a non-numeric 798 uid/gid. 800 Strawman NFS version 4 August 1998 802 6. Defined Error Numbers 804 NFS error numbers are assigned to failed operations within a compound 805 request. A compound request contains a number of NFS operations that 806 have their results encoded in sequence in a compound reply. The 807 results of successful operations will consist of an NFS4_OK status 808 followed by the encoded results of the operation. If an NFS 809 operation fails, an error status will be entered in the reply and the 810 compound request will be terminated. 812 A description of each defined error follows: 814 NFS4_OK Indicates the operation completed successfully. 816 NFS4ERR_PERM Not owner. The operation was not allowed because 817 the caller is either not a privileged user (root) 818 or not the owner of the target of the operation. 820 NFS4ERR_NOENT No such file or directory. The file or directory 821 name specified does not exist. 823 NFS4ERR_IO I/O error. A hard error (for example, a disk 824 error) occurred while processing the requested 825 operation. 827 NFS4ERR_NXIO I/O error. No such device or address. 829 NFS4ERR_ACCES Permission denied. The caller does not have the 830 correct permission to perform the requested 831 operation. Contrast this with NFS4ERR_PERM, which 832 restricts itself to owner or privileged user 833 permission failures. 835 NFS4ERR_DENIED An attempt to lock a file is denied. Since this 836 may be a temporary condition, the client is 837 encouraged to retry the lock request (with 838 exponential backoff of timeout) until the lock is 839 accepted. 841 NFS4ERR_EXIST File exists. The file specified already exists. 843 Strawman NFS version 4 August 1998 845 NFS4ERR_XDEV Attempt to do a cross-device hard link. 847 NFS4ERR_NODEV No such device. 849 NFS4ERR_NOTDIR Not a directory. The caller specified a non- 850 directory in a directory operation. 852 NFS4ERR_ISDIR Is a directory. The caller specified a directory 853 in a non-directory operation. 855 NFS4ERR_INVAL Invalid argument or unsupported argument for an 856 operation. Two examples are attempting a READLINK 857 on an object other than a symbolic link or 858 attempting to SETATTR a time field on a server 859 that does not support this operation. 861 NFS4ERR_FBIG File too large. The operation would have caused a 862 file to grow beyond the server's limit. 864 NFS4ERR_NOSPC No space left on device. The operation would have 865 caused the server's file system to exceed its 866 limit. 868 NFS4ERR_ROFS Read-only file system. A modifying operation was 869 attempted on a read-only file system. 871 NFS4ERR_MLINK Too many hard links. 873 NFS4ERR_NAMETOOLONG The filename in an operation was too long. 875 NFS4ERR_NOTEMPTY An attempt was made to remove a directory that 876 was not empty. 878 NFS4ERR_DQUOT Resource (quota) hard limit exceeded. The user's 879 resource limit on the server has been exceeded. 881 Strawman NFS version 4 August 1998 883 NFS4ERR_LOCKED A read or write operation was attempted on a 884 locked file. 886 NFS4ERR_STALE Invalid file handle. The file handle given in the 887 arguments was invalid. The file referred to by 888 that file handle no longer exists or access to it 889 has been revoked. 891 NFS4ERR_BADHANDLE Illegal NFS file handle. The file handle failed 892 internal consistency checks. 894 NFS4ERR_NOT_SYNC Update synchronization mismatch was detected 895 during a SETATTR operation. 897 NFS4ERR_BAD_COOKIE READDIR cookie is stale. 899 NFS4ERR_NOTSUPP Operation is not supported. 901 NFS4ERR_TOOSMALL Buffer or request is too small. 903 NFS4ERR_SAME Returned if an NVERIFY operation shows that no 904 attributes have changed. 906 NFS4ERR_SERVERFAULT An error occurred on the server which does not 907 map to any of the legal NFS version 4 protocol 908 error values. The client should translate this 909 into an appropriate error. UNIX clients may 910 choose to translate this to EIO. 912 NFS4ERR_BADTYPE An attempt was made to create an object of a type 913 not supported by the server. 915 NFS4ERR_JUKEBOX The server initiated the request, but was not 916 able to complete it in a timely fashion. The 917 client should wait and then try the request with 918 a new RPC transaction ID. For example, this 919 error should be returned from a server that 920 supports hierarchical storage and receives a 922 Strawman NFS version 4 August 1998 924 request to process a file that has been migrated. 925 In this case, the server should start the 926 immigration process and respond to client with 927 this error. 929 NFS4ERR_FHEXPIRED The file handle provided is volatile and has 930 expired at the server. The client should attempt 931 to recover the new file handle by traversing the 932 server's file system name space. The file handle 933 may have expired because the server has 934 restarted, the file system object has been 935 removed, or the file handle has been flushed from 936 the server's internal mappings. 938 NOTE: This error definition will need to be crisp and match 939 the section describing the volatile file handles. 941 NFS4ERR_WRONGSEC THe security mechanism being used by the client 942 for the procedure does not match the server's 943 security policy. The client should change the 944 security mechanism being used and retry the 945 operation. 947 Strawman NFS version 4 August 1998 949 7. Compound Requests 951 NFS version 4 allows a client to combine multiple NFS operations into 952 a single request. Compound requests provide: 954 o Good performance on high latency networks 956 If a client can combine multiple, dependent operations into a 957 single request then it can avoid the cumulative latency in many 958 request/response round-trips across the network. This is 959 particularly important on the Internet or through geosynchronous 960 satellite connections. 962 o Protocol simplification 964 Clients can build NFS requests of arbitrary complexity from more 965 primitive operations. These requests can be tailored to the 966 unique needs of each client. 968 A compound request looks like this: 970 +-----------+-----------+-----------+-- 971 | op + args | op + args | op + args | 972 +-----------+-----------+-----------+-- 974 and the reply looks like this: 976 +----------------+----------------+----------------+-- 977 | code + results | code + results | code + results | 978 +----------------+----------------+----------------+-- 980 Where "code" is an indication of the success or failure of the 981 operation including the opcode itself. 983 Strawman NFS version 4 August 1998 985 8. NFS Version 4 Requests 987 Nearly all NFS version 4 operations are defined as compound 988 operations - not as RPC procedures. There is a single RPC procedure 989 for all compound requests. 991 NOTE: Let's imagine procedure 1 is defined as a compound 992 request. Procedure 2 might be a proxied compound request, 993 i.e. a compound request with a header that identifies the 994 target server. 996 8.1. Evaluation of a Compound Request 998 NOTE: A useful initial prefix on a compound request 999 sequence would be a string that summarizes the content of 1000 the compound request for the benefit of packet sniffers 1001 like snoop and engineers debugging implementations. 1003 The server evaluates the operations in sequence. Each operation 1004 consists of a 32 bit operation code, followed by a sequence of 1005 arguments of length determined by the type of operation. The results 1006 of each operation are encoded in sequence into a reply buffer. The 1007 results of each operation are preceded by the opcode and a status 1008 code (normally zero). If an operation fails a non-zero status code 1009 will be encoded, evaluation of the compound request will halt, and 1010 the reply will be returned. 1012 The client is responsible for recovering from any partially completed 1013 compound request. 1015 Each operation assumes a "current" filehandle that is available as 1016 part of the execution context of the compound request. Operations 1017 may set, change, or return this filehandle. 1019 Strawman NFS version 4 August 1998 1021 9. NFS Version 4 Procedures 1022 Strawman NFS version 4 August 1998 1024 9.1. Procedure 0: NULL - No operation 1026 SYNOPSIS 1028 (cfh) -> (cfh) 1030 ARGS 1032 (none) 1034 RESULTS 1036 (none) 1038 DESCRIPTION 1040 The server does no work other than to return a NFS_OK result in 1041 the reply. 1043 ERRORS 1045 (none) 1047 Strawman NFS version 4 August 1998 1049 9.2. Procedure 1: ACCESS - Check Access Permission 1051 SYNOPSIS 1053 (cfh), permbits -> permbits 1055 ARGS 1057 permbits: uint32 1059 RESULTS 1061 permbits: uint32 1063 DESCRIPTION 1065 ACCESS determines the access rights that a user, as identified by 1066 the credentials in the request, has with respect to a file system 1067 object. The client encodes the set of permissions that are to be 1068 checked in a bit mask. The server checks the permissions encoded 1069 in the bit mask. A status of NFS4_OK is returned along with a bit 1070 mask encoded with the permissions that the client is allowed. 1072 The results of this procedure are necessarily advisory in nature. 1073 That is, a return status of NFS4_OK and the appropriate bit set in 1074 the bit mask does not imply that such access will be allowed to 1075 the file system object in the future, as access rights can be 1076 revoked by the server at any time. 1078 The following access permissions may be requested: 1080 ACCESS_READ: bit 0 Read data from file or read 1081 a directory. 1082 ACCESS_LOOKUP: bit 1 Look up a name in a 1083 directory (no meaning for 1084 non-directory objects). 1085 ACCESS_MODIFY: bit 2 Rewrite existing file data or modify 1086 existing directory entries. 1087 ACCESS_EXTEND: bit 3 Write new data or add 1088 directory entries. 1089 ACCESS_DELETE: bit 4 Delete an existing 1090 directory entry. 1091 ACCESS_EXECUTE: bit 5 Execute file (no meaning 1092 for a directory). 1094 Strawman NFS version 4 August 1998 1096 The server must return an error if the any access permission 1097 cannot be determined. 1099 IMPLEMENTATION 1101 In general, it is not sufficient for the client to attempt to 1102 deduce access permissions by inspecting the uid, gid, and mode 1103 fields in the file attributes, since the server may perform uid or 1104 gid mapping or enforce additional access control restrictions. It 1105 is also possible that the NFS version 4 protocol server may not be 1106 in the same ID space as the NFS version 4 protocol client. In 1107 these cases (and perhaps others), the NFS version 4 protocol 1108 client can not reliably perform an access check with only current 1109 file attributes. 1111 In the NFS version 2 protocol, the only reliable way to determine 1112 whether an operation was allowed was to try it and see if it 1113 succeeded or failed. Using the ACCESS procedure in the NFS version 1114 4 protocol, the client can ask the server to indicate whether or 1115 not one or more classes of operations are permitted. The ACCESS 1116 operation is provided to allow clients to check before doing a 1117 series of operations. This is useful in operating systems (such as 1118 UNIX) where permission checking is done only when a file or 1119 directory is opened. This procedure is also invoked by NFS client 1120 access procedure (called possibly through access(2)). The intent 1121 is to make the behavior of opening a remote file more consistent 1122 with the behavior of opening a local file. 1124 The information returned by the server in response to an ACCESS 1125 call is not permanent. It was correct at the exact time that the 1126 server performed the checks, but not necessarily afterwards. The 1127 server can revoke access permission at any time. 1129 The NFS version 4 protocol client should use the effective 1130 credentials of the user to build the authentication information in 1131 the ACCESS request used to determine access rights. It is the 1132 effective user and group credentials that are used in subsequent 1133 read and write operations. 1135 Many implementations do not directly support the ACCESS_DELETE 1136 permission. Operating systems like UNIX will ignore the 1137 ACCESS_DELETE bit if set on an access request on a non-directory 1138 object. In these systems, delete permission on a file is 1139 determined by the access permissions on the directory in which the 1140 file resides, instead of being determined by the permissions of 1141 the file itself. Thus, the bit mask returned for such a request 1142 will have the ACCESS_DELETE bit set to 0, indicating that the 1143 client does not have this permission. 1145 Strawman NFS version 4 August 1998 1147 ERRORS 1149 NFS4ERR_IO 1151 NFS4ERR_SERVERFAULT 1153 SEE 1155 GETATTR. 1157 Strawman NFS version 4 August 1998 1159 9.3. Procedure 2: COMMIT - Commit cached data 1161 SYNOPSIS 1163 (cfh), offset, count -> verifier 1165 Procedure COMMIT forces or flushes data to stable storage that was 1166 previously written with a WRITE operation with the stable field 1167 set to UNSTABLE. 1169 ARGS 1171 offset: uint64 1173 The position within the file at which the flush is to begin. An 1174 offset of 0 means to flush data starting at the beginning of the 1175 file. 1177 count: uint32 1179 The number of bytes of data to flush. If count is 0, a flush from 1180 offset to the end of file is done. 1182 RESULTS 1184 verifier: uint32 1186 This is a cookie that the client can use to determine whether the 1187 server has rebooted between a call to WRITE and a subsequent call 1188 to COMMIT. This cookie must be consistent during a single boot 1189 session and must be unique between instances of the NFS version 4 1190 protocol server where uncommitted data may be lost. 1192 IMPLEMENTATION 1194 Procedure COMMIT is similar in operation and semantics to the 1195 POSIX fsync(2) system call that synchronizes a file's state with 1196 the disk, that is it flushes the file's data and metadata to disk. 1197 COMMIT performs the same operation for a client, flushing any 1198 unsynchronized data and metadata on the server to the server's 1199 disk for the specified file. Like fsync(2), it may be that there 1200 is some modified data or no modified data to synchronize. The data 1201 may have been synchronized by the server's normal periodic buffer 1202 synchronization activity. COMMIT will always return NFS4_OK, 1203 unless there has been an unexpected error. 1205 COMMIT differs from fsync(2) in that it is possible for the client 1207 Strawman NFS version 4 August 1998 1209 to flush a range of the file (most likely triggered by a buffer- 1210 reclamation scheme on the client before file has been completely 1211 written). 1213 The server implementation of COMMIT is reasonably simple. If the 1214 server receives a full file COMMIT request, that is starting at 1215 offset 0 and count 0, it should do the equivalent of fsync()'ing 1216 the file. Otherwise, it should arrange to have the cached data in 1217 the range specified by offset and count to be flushed to stable 1218 storage. In both cases, any metadata associated with the file 1219 must be flushed to stable storage before returning. It is not an 1220 error for there to be nothing to flush on the server. This means 1221 that the data and metadata that needed to be flushed have already 1222 been flushed or lost during the last server failure. 1224 The client implementation of COMMIT is a little more complex. 1225 There are two reasons for wanting to commit a client buffer to 1226 stable storage. The first is that the client wants to reuse a 1227 buffer. In this case, the offset and count of the buffer are sent 1228 to the server in the COMMIT request. The server then flushes any 1229 cached data based on the offset and count, and flushes any 1230 metadata associated with the file. It then returns the status of 1231 the flush and the verf verifier. The other reason for the client 1232 to generate a COMMIT is for a full file flush, such as may be done 1233 at close. In this case, the client would gather all of the buffers 1234 for this file that contain uncommitted data, do the COMMIT 1235 operation with an offset of 0 and count of 0, and then free all of 1236 those buffers. Any other dirty buffers would be sent to the 1237 server in the normal fashion. 1239 This implementation will require some modifications to the buffer 1240 cache on the client. After a buffer is written with stable 1241 UNSTABLE, it must be considered as dirty by the client system 1242 until it is either flushed via a COMMIT operation or written via a 1243 WRITE operation with stable set to FILE_SYNC or DATA_SYNC. This is 1244 done to prevent the buffer from being freed and reused before the 1245 data can be flushed to stable storage on the server. 1247 When a response comes back from either a WRITE or a COMMIT 1248 operation that contains an unexpected verf, the client will need 1249 to retransmit all of the buffers containing uncommitted cached 1250 data to the server. How this is to be done is up to the 1251 implementor. If there is only one buffer of interest, then it 1252 should probably be sent back over in a WRITE request with the 1253 appropriate stable flag. If there more than one, it might be 1254 worthwhile retransmitting all of the buffers in WRITE requests 1255 with stable set to UNSTABLE and then retransmitting the COMMIT 1256 operation to flush all of the data on the server to stable 1258 Strawman NFS version 4 August 1998 1260 storage. The timing of these retransmissions is left to the 1261 implementor. 1263 The above description applies to page-cache-based systems as well 1264 as buffer-cache-based systems. In those systems, the virtual 1265 memory system will need to be modified instead of the buffer 1266 cache. 1268 ERRORS 1270 NFS4ERR_IO NFS4ERR_LOCKED NFS4ERR_SERVERFAULT 1272 SEE 1274 WRITE. 1276 Strawman NFS version 4 August 1998 1278 9.4. Procedure 3: CREATE - Create a filesystem object 1280 SYNOPSIS 1282 (cfh), name, type, how -> (cfh) 1284 ARGS 1286 name: utf8string 1288 objtype: filetype 1290 how: union 1292 UNCHECKED: 1293 GUARDED: 1295 attrbits: bitmap 1296 attrvals 1298 EXCLUSIVE: 1300 verifier: createverf 1302 RESULTS 1304 (cfh): filehandle 1306 DESCRIPTION 1308 Procedure CREATE creates an object in a directory with a given 1309 name. The objtype determines the type of object to be created: 1310 directory, regular file, etc. The how union may have a value of 1311 UNCHECKED, GUARDED, and EXCLUSIVE. UNCHECKED means that the object 1312 should be created without checking for the existence of a 1313 duplicate object in the same directory. In this case, attrbits and 1314 attrvals describe the initial attributes for the file. GUARDED 1315 specifies that the server should check for the presence of a 1316 duplicate object before performing the create and should fail the 1317 request with NFS4ERR_EXIST if a duplicate object exists. If the 1318 object does not exist, the request is performed as described for 1319 UNCHECKED. EXCLUSIVE specifies that the server is to follow 1320 exclusive creation semantics, using the verifier to ensure 1321 exclusive creation of the target. No attributes may be provided in 1322 this case, since the server may use the target object metadata to 1323 store the verifier. 1325 Strawman NFS version 4 August 1998 1327 The current filehandle is replaced by that of the new object. 1329 IMPLEMENTATION 1330 The CREATE procedure carries support for EXCLUSIVE create forward 1331 from NFS version 3. As in NFS version 3, this mechanism provides 1332 reliable exclusive creation. Exclusive create is invoked when the 1333 how parameter is EXCLUSIVE. In this case, the client provides a 1334 verifier that can reasonably be expected to be unique. A 1335 combination of a client identifier, perhaps the client network 1336 address, and a unique number generated by the client, perhaps the 1337 RPC transaction identifier, may be appropriate. 1339 If the object does not exist, the server creates the object and 1340 stores the verifier in stable storage. For file systems that do 1341 not provide a mechanism for the storage of arbitrary file 1342 attributes, the server may use one or more elements of the object 1343 metadata to store the verifier. The verifier must be stored in 1344 stable storage to prevent erroneous failure on retransmission of 1345 the request. It is assumed that an exclusive create is being 1346 performed because exclusive semantics are critical to the 1347 application. Because of the expected usage, exclusive CREATE does 1348 not rely solely on the normally volatile duplicate request cache 1349 for storage of the verifier. The duplicate request cache in 1350 volatile storage does not survive a crash and may actually flush 1351 on a long network partition, opening failure windows. In the UNIX 1352 local file system environment, the expected storage location for 1353 the verifier on creation is the metadata (time stamps) of the 1354 object. For this reason, an exclusive object create may not 1355 include initial attributes because the server would have nowhere 1356 to store the verifier. 1358 If the server can not support these exclusive create semantics, 1359 possibly because of the requirement to commit the verifier to 1360 stable storage, it should fail the CREATE request with the error, 1361 NFS4ERR_NOTSUPP. 1363 During an exclusive CREATE request, if the object already exists, 1364 the server reconstructs the object's verifier and compares it with 1365 the verifier in the request. If they match, the server treats the 1366 request as a success. The request is presumed to be a duplicate of 1367 an earlier, successful request for which the reply was lost and 1368 that the server duplicate request cache mechanism did not detect. 1369 If the verifiers do not match, the request is rejected with the 1370 status, NFS4ERR_EXIST. 1372 Once the client has performed a successful exclusive create, it 1373 must issue a SETATTR to set the correct object attributes. Until 1374 it does so, it should not rely upon any of the object attributes, 1376 Strawman NFS version 4 August 1998 1378 since the server implementation may need to overload object 1379 metadata to store the verifier. 1381 Use of the GUARDED attribute does not provide exactly-once 1382 semantics. In particular, if a reply is lost and the server does 1383 not detect the retransmission of the request, the procedure can 1384 fail with NFS4ERR_EXIST, even though the create was performed 1385 successfully. 1387 Note: 1389 1. Need to determine an initial set of attributes 1390 that must be set, and a set of attributes that 1391 can optionally be set, on a per-filetype basis. 1392 For instance, if the filetype is a NF4BLK then 1393 the device attributes must be set. 1395 2. Need to consider the symbolic link path as 1396 an "attribute". No need for a READLINK op 1397 if this is so. Similarly, a filehandle could 1398 be defined as an attribute for LINK. 1400 3. The presence of a generic create for 1401 multiple filetypes makes the protocol 1402 easier to extend to new filetypes in 1403 a minor rev (without defining new ops) 1405 4. The specific exclusive create semantics can be 1406 removed if there is guaranteed support for extended 1407 attributes. The client could specify the verifier 1408 be stored in an extended attribute and then check 1409 the attribute value itself instead of relying on the 1410 server to do so. 1412 ERRORS 1414 NFS4ERR_IO 1416 NFS4ERR_ACCES 1418 NFS4ERR_EXIST 1420 NFS4ERR_NOTDIR 1422 NFS4ERR_NOSPC 1424 Strawman NFS version 4 August 1998 1426 NFS4ERR_ROFS 1428 NFS4ERR_NAMETOOLONG 1430 NFS4ERR_DQUOT 1432 NFS4ERR_NOTSUPP 1434 NFS4ERR_SERVERFAULT 1436 Strawman NFS version 4 August 1998 1438 9.5. Procedure 4: GETATTR - Get attributes 1440 SYNOPSIS 1442 (cfh), attrbits -> attrbits, attrvals 1444 ARGS 1446 attrbits: bitmap 1448 RESULTS 1450 attrbits: bitmap 1452 attrvals: sequence of attributes 1454 DESCRIPTION 1456 Obtain attributes from the server. The client sets a bit in the 1457 bitmap argument for each attribute value that it would like the 1458 server to return. The server returns an attribute bitmap that 1459 indicates the attribute values that it was able to return, 1460 followed by the attribute values ordered lowest attribute number 1461 first. 1463 The server must return a value for each attribute that the client 1464 requests if the attribute is supported by the server. If the 1465 server does not support an attribute or cannot approximate a 1466 useful value then it must not return the attribute value and must 1467 not set the attribute bit in the result bitmap. The server must 1468 return an error if it supports an attribute but cannot obtain its 1469 value. In that case no attribute values will be returned. 1471 All servers must support attribute 0 which is a bitmap of all 1472 supported attributes for the filesystem object. 1474 IMPLEMENTATION 1476 ? 1478 ERRORS 1480 NFS4ERR_IO 1482 NFS4ERR_SERVERFAULT 1484 Strawman NFS version 4 August 1998 1486 9.6. Procedure 5: GETFH - Get current filehandle 1488 SYNOPSIS 1490 (cfh) -> filehandle 1492 ARGS 1494 RESULTS 1496 filehandle: filehandle 1498 DESCRIPTION 1500 Returns the current filehandle. Operations that change the 1501 current filehandle like LOOKUP or CREATE to not automatically 1502 return the new filehandle as a result. For instance, if a client 1503 needs to lookup a directory entry and obtain its filehandle then 1504 the following request will do it: 1506 1: PUTFH (directory filehandle) 1507 2: LOOKUP (entry name) 1508 3: GETFH 1510 IMPLEMENTATION 1512 ? 1514 ERRORS 1516 NFS4ERR_SERVERFAULT 1518 Strawman NFS version 4 August 1998 1520 9.7. Procedure 6: LINK - Create link to an object 1522 SYNOPSIS 1524 (cfh), dir, newname -> (cfh) 1526 ARGS 1528 dir: filehandle 1530 newname: utf8string 1532 RESULTS 1534 (none) 1536 DESCRIPTION 1538 Procedure LINK creates an additional newname for the file with the 1539 current filehandle in the new directory dir file and link.dir must 1540 reside on the same file system and server. On entry, the arguments 1541 in LINK3args are: 1543 IMPLEMENTATION 1545 Changes to any property of the hard-linked files are reflected in 1546 all of the linked files. When a hard link is made to a file, the 1547 attributes for the file should have a value for nlink that is one 1548 greater than the value before the LINK. 1550 The comments under RENAME regarding object and target residing on 1551 the same file system apply here as well. The comments regarding 1552 the target name applies as well. 1554 ERRORS 1556 NFS4ERR_IO 1558 NFS4ERR_ACCES 1560 NFS4ERR_EXIST 1562 NFS4ERR_XDEV 1564 NFS4ERR_NOTDIR 1566 Strawman NFS version 4 August 1998 1568 NFS4ERR_INVAL 1570 NFS4ERR_NOSPC 1572 NFS4ERR_ROFS 1574 NFS4ERR_MLINK 1576 NFS4ERR_NAMETOOLONG 1578 NFS4ERR_DQUOT 1580 NFS4ERR_NOTSUPP 1582 NFS4ERR_SERVERFAULT 1584 Strawman NFS version 4 August 1998 1586 9.8. Procedure 7: LOCKR - Create a read lock 1588 SYNOPSIS 1590 (cfh), id, offset, length -> lease 1592 ARGS 1594 id: uint64 1596 offset: uint64 1598 length: uint64 1600 RESULTS 1602 lease: uint32 1604 DESCRIPTION 1606 Requested by a client that needs to protect a file extent from 1607 change. Other clients may have read locks that overlap the extent 1608 completely or partially but no other client or server process will 1609 be allowed to modify or create an overlapping write lock on the 1610 extent until there are no read or write locks covering any part of 1611 the extent. A write lock will be granted only when the leases for 1612 conflicting locks have expired, or because all clients have 1613 removed their locks. The locked extent is permitted to lie 1614 partially or completely beyond the end of the file. The id is a 1615 64-bit value that the client provides to uniquely identify its 1616 lock. The server will attempt to match this value with a 1617 subsequent LOCKX or LOCKU request. 1619 A read-lock will receive an NFS4_DENIED error if another client 1620 has requested a write-lock or is holding a write lock on any part 1621 of the requested extent. The returned lease time is the time 1622 remaining on the lock-holder's lease. 1624 IMPLEMENTATION 1626 A read lock is mandatory. The server must prevent other clients 1627 or local processes from changing the locked extent of the file 1628 while the read lock is held. 1630 A duplicate read-lock request must be treated as an idempotent 1631 operation and must not return an error. 1633 Strawman NFS version 4 August 1998 1635 A LOCKR may be combined with a READ in a compound request so that 1636 the data be locked and read in a single operation: 1638 1: PUTFH 0x12345 1639 2: LOCKR 123 0,8192 1640 3: READ 0,8192 1642 or perhaps 1644 1: PUTFH 0x12345 1645 2: READ 0,8192 1646 3: LOCKR 123 0,8192 1648 allowing the client to read the data unconditionally yet change 1649 its caching strategy depending on whether the lock is granted. 1651 ERRORS 1653 NFS4ERR_DENIED 1655 NFS4ERR_IO 1657 NFS4ERR_NXIO 1659 NFS4ERR_ACCES 1661 NFS4ERR_INVAL 1663 NFS4ERR_SERVERFAULT 1665 Strawman NFS version 4 August 1998 1667 9.9. Procedure 8: LOCKW - Create write lock 1669 SYNOPSIS 1671 (cfh) id, offset, length -> lease 1673 ARGS 1675 id: uint64 1677 offset: uint64 1679 length: uint64 1681 RESULTS 1683 lease: uint32 1685 DESCRIPTION 1687 Requested by a client that needs to change a file. While a write 1688 lock is held, no other client can read the locked extent or obtain 1689 either a read lock or a write lock for the same extent. The locked 1690 extent is permitted to lie partially or completely beyond the end 1691 of the file. The id is a 64-bit value that the client provides to 1692 uniquely identify the lock. The server will attempt to match this 1693 value with a subsequent LOCKX or LOCKU request. 1695 An NFS4ERR_DENIED error will be returned if one or more other 1696 clients are holding a read or write lock on any part of the 1697 requested extent. The client should continue to retransmit the 1698 lock request (using exponential backoff to avoid server overload) 1699 until the request is granted. The client will not be granted a 1700 write lock for an extent that overlaps an extent that it has write 1701 locked previously. When the server rejects a write lock request it 1702 should prevent clients from renewing or obtaining new read locks 1703 for the same file for some reasonable period of time. This policy 1704 prevents write starvation. 1706 IMPLEMENTATION 1708 The server might employ a "fairness" scheme to arbitrate between 1709 multiple clients attempting write locks, e.g. client lock requests 1710 be ordered so that the first requester is given the preference 1711 window when the write lock becomes available. 1713 NOTE: Could get some interesting dynamics here where there 1715 Strawman NFS version 4 August 1998 1717 is much contention for read and write locks on a single 1718 file. I haven't begun to think about possible problems 1719 when a file becomes popular. I'm concerned that we keep 1720 the protocol simple and easy to understand - leaving 1721 implementations to focus on topics like "fairness" and 1722 "performance." 1724 A LOCKW may be combined with a READ in a compound request followed by 1725 a subsequent combination of WRITE and LOCKU where the client writes 1726 back the updated record/file, e.g. 1728 1: PUTFH 0x12345 1729 2: LOCKW 123 0,8192 1730 3: READ 0,8192 1732 Client updates data, then 1734 1: PUTFH 0x12345 1735 2: LOCKX 123 0,8192 1736 3: WRITE 0,8192 1737 4: LOCKU 123 0,8192 1739 Note the use of a LOCKX to abort the transaction if the lock has been 1740 lost. It also seems a reasonable requirement that if a lOCKX is 1741 granted that it be valid for at least the duration of the compound 1742 request. 1744 ERRORS 1746 NFS4ERR_DENIED 1748 NFS4ERR_ACCES 1750 NFS4ERR_SERVERFAULT 1752 Strawman NFS version 4 August 1998 1754 9.10. Procedure 9: LOCKT - test for lock 1756 SYNOPSIS 1758 (cfh), offset, length -> lockstate 1760 ARGS 1762 offset: uint64 1764 length: uint64 1766 RESULTS 1768 lockstate: uint32 1770 DESCRIPTION 1772 Requested by a client that needs to establish whether any part of 1773 an extent in a file is locked. The server returns one of three 1774 lock states: 1776 0 - Unlocked 1777 1 - Read lock held 1778 2 - Write lock held 1780 ERRORS 1782 NFS4ERR_ACCES 1784 NFS4ERR_SERVERFAULT 1786 Strawman NFS version 4 August 1998 1788 9.11. Procedure 10: LOCKX - validate and extend lock 1790 SYNOPSIS 1792 (cfh) id, offset, length, locktype -> lease 1794 ARGS 1796 id: uint64 1798 offset: uint64 1800 length: uint64 1802 locktype: enum { READLOCK | WRITELOCK } 1804 RESULTS 1806 lease: uint32 1808 DESCRIPTION 1810 Requested by a client that wishes to extend the lease on a read or 1811 write lock. The id, offset, and length must match a previous 1812 successful LOCKR or LOCKW request. If successful, the server 1813 returns the remaining time for the new lease. A LOCKX operation 1814 must precede any READ or WRITE operation in the compound request 1815 that assumes the extent is locked. This serves two purposes: it 1816 assures the client that the server is still holding the lock (the 1817 server may have lost the lock for some reason) and it validates to 1818 the server that the client holds the lock. Without this validation 1819 the server will deny any read or write request on a locked file. 1821 An NFS4ERR_EXPIRED error means that the server has lost the lock, 1822 or that the client's lease expired before the client could renew 1823 it. The client must take appropriate recovery action and request 1824 a new lease. A lease could expire if the client attempted a lock 1825 extension close to the expiry time and the request was lost or 1826 dropped. In that case the retransmission of the extension request 1827 might arrive at the server after expiry. 1829 IMPLEMENTATION 1831 Even though an extension request might arrive after expiry, a 1832 benevolent server may grant the extension if it notices that there 1833 have been no other changes to the file since the expiry. 1835 Strawman NFS version 4 August 1998 1837 Note the server may acknowledge the ownership of the lock but deny 1838 a lease extension. In this case the lease time returned will be 1839 the time remaining on the original lease. 1841 The server must implement a "grace" period after a crash in which 1842 it will monitor all requests but respond to none. During the grace 1843 period information from LOCKX operations will be used to rebuild 1844 lock state. 1846 NOTE: Assumption here that if the server can recover very 1847 quickly, well within the lease times, then it might use the 1848 client's renewal requests to recover lock state. In the 1849 case where clients are unable to extend leases because the 1850 server is down and their leases expire, they should 1851 continue to attempt lease extensions in the hope that the 1852 grace period will allow recovery. The worst that can 1853 happen is that they miss the grace period, or that they 1854 lost the lease because of network partition (or server 1855 overload) and the lease extension is denied. 1857 ERRORS 1859 NFS4ERR_EXPIRED 1861 NFS4ERR_ACCES 1863 NFS4ERR_SERVERFAULT 1865 Strawman NFS version 4 August 1998 1867 9.12. Procedure 11: LOCKU - Unlock file 1869 SYNOPSIS 1871 (cfh) id, offset, length -> - 1873 ARGS 1875 id: uint64 1877 offset: uint64 1879 length: uint64 1881 DESCRIPTION 1883 Unlock read or write lock for a file extent. The id, offset, and 1884 length must match that of a previous successful LOCKR or LOCKW 1885 request. 1887 An NFS4ERR_EXPIRED error means that the server has no knowledge of 1888 the client's lock - most likely the lease expired. In this 1889 situation the client may choose to take some recovery action. 1891 ERRORS 1893 NFS4ERR_EXPIRED 1895 NFS4ERR_ACCES 1897 NFS4ERR_SERVERFAULT 1899 Strawman NFS version 4 August 1998 1901 9.13. Procedure 12: LOOKUP - Lookup filename 1903 SYNOPSIS 1905 (cfh), filenames -> (cfh) 1907 ARGS 1909 filename: utf8string[] 1911 RESULTS 1913 (none) 1915 DESCRIPTION 1917 The current filehandle is assumed to refer to a directory. LOOKUP 1918 evaluates the pathname contained in the array of names and obtains 1919 a new current filehandle from the final name. All but the final 1920 name in the list must be the names of directories. 1922 If the pathname cannot be evaluated either because a component 1923 doesn't exist or because the client doesn't have permission to 1924 evaluate a component of the path, then an error will be returned 1925 and the current filehandle will be unchanged. 1927 IMPLEMENTATION 1929 If the client prefers a partial evaluation of the path then a 1930 sequence of LOOKUP operations can be substituted e.g. 1932 1. PUTFH (directory filehandle) 1933 2. LOOKUP "pub" "foo" "bar" 1934 3. GETFH 1936 or 1938 1. PUTFH (directory filehandle) 1939 2. LOOKUP "pub" 1940 3. GETFH 1941 4. LOOKUP "foo" 1942 5. GETFH 1943 6. LOOKUP "bar" 1944 7. GETFH 1946 NFS version 4 servers depart from the semantics of previous NFS 1947 versions in allowing LOOKUP requests to cross mountpoints on the 1949 Strawman NFS version 4 August 1998 1951 server. The client can detect a mountpoint crossing by comparing 1952 the fsid attribute of the directory with the fsid attribute of the 1953 directory looked up. If the fsids are different then the new 1954 directory is a server mountpoint. Unix clients that detect a 1955 mountpoint crossing will need to mount the server's filesystem. 1957 Servers that limit NFS access to "shares" or "exported" 1958 filesystems should provide a pseudo-filesystem into which the 1959 exported filesystems can be integrated, so that clients can browse 1960 the server's namespace. The clients view of a pseudo filesystem 1961 will be limited to paths that lead to exported filesystems. 1963 Note: previous versions of the protocol assigned special semantics 1964 to the names "." and "..". NFS version 4 assigns no special 1965 semantics to these names. The LOOKUPP operator must be used to 1966 lookup a parent directory. 1968 Note that this procedure does not follow symbolic links. The 1969 client is responsible for all parsing of filenames including 1970 filenames that are modified by symbolic links encountered during 1971 the lookup process. 1973 ERRORS 1975 NFS4ERR_IO 1977 NFS4ERR_NOENT 1979 NFS4ERR_ACCES 1981 NFS4ERR_NOTDIR 1983 NFS4ERR_NAMETOOLONG 1985 NFS4ERR_SERVERFAULT 1987 SEE 1989 CREATE 1991 Strawman NFS version 4 August 1998 1993 9.14. Procedure 13: LOOKUPP - Lookup parent directory 1995 SYNOPSIS 1997 (cfh) -> (cfh) 1999 ARGS 2001 (none) 2003 RESULTS 2005 (none) 2007 DESCRIPTION 2009 The current filehandle is assumed to refer to a directory. 2010 LOOKUPP assigns the filehandle for its parent directory to be the 2011 current filehandle. If there is no parent directory an ENOENT 2012 error must be returned. 2014 IMPLEMENTATION 2016 As for LOOKUP, LOOKUPP will also cross mountpoints. 2018 ERRORS 2020 NFS4ERR_IO 2022 NFS4ERR_NOENT 2024 NFS4ERR_ACCES 2026 NFS4ERR_SERVERFAULT 2028 SEE 2030 CREATE 2032 Strawman NFS version 4 August 1998 2034 9.15. Procedure 14: NVERIFY - Verify attributes different 2036 SYNOPSIS 2038 (cfh), attrbits, attrvals -> - 2040 ARGS 2042 attrbits: bitmap 2044 attrvals: sequence of attributes 2046 RESULTS 2048 (none) 2050 DESCRIPTION 2052 This operation is used to prefix a sequence of operations to be 2053 performed if one or more attributes have changed on some 2054 filesystem object. If all the attributes match then the error 2055 NFS4ERR_SAME must be returned. 2057 IMPLEMENTATION 2059 This operation is useful as a cache validation operator. If the 2060 object to which the attributes belong has changed then the 2061 following operations may obtain new data associated with that 2062 object. For instance, to check if a file has been changed and 2063 obtain new data if it has: 2065 1. PUTFH (public) 2066 2. LOOKUP "pub" "foo" "bar" 2067 3. NVERIFY attrbits attrs 2068 4. READ 0 32767 2070 ERRORS 2072 NFS4ERR_IO 2074 NFS4ERR_ACCES 2076 NFS4ERR_SERVERFAULT 2078 NFS4ERR_SAME 2080 Strawman NFS version 4 August 1998 2082 9.16. Procedure 15: RESTOREFH - Restore saved filehandle 2084 SYNOPSIS 2086 (sfh) -> (cfh) 2088 ARGS 2090 (none) 2092 RESULTS 2094 (none) 2096 DESCRIPTION 2098 Make the saved filehandle the current filehandle. If there is no 2099 saved filehandle then return an error NFS4ERR_INVAL. 2101 IMPLEMENTATION 2103 Operators like CREATE and LOOKUP use the current filehandle to 2104 represent a directory and replace it with a new filehandle. 2105 Assuming the previous filehandle was saved with a SAVEFH operator, 2106 the previous filehandle can be restored as the current filehandle. 2107 This is commonly used to obtain post-operation attributes for the 2108 directory, e.g. 2110 1. PUTFH (directory filehandle) 2111 2. SAVEFH 2112 3. GETATTR attrbits (pre-op dir attrs) 2113 4. CREATE optbits "foo" attrs 2114 5. GETATTR attrbits (file attributes) 2115 6. RESTOREFH 2116 7. GETATTR attrbits (post-op dir attrs) 2118 ERRORS 2120 NFS4ERR_SERVERFAULT 2122 Strawman NFS version 4 August 1998 2124 9.17. Procedure 16: SAVEFH - Save current filehandle 2126 SYNOPSIS 2128 (cfh) -> (sfh) 2130 ARGS 2132 (none) 2134 RESULTS 2136 (none) 2138 DESCRIPTION 2140 Save the current filehandle. If a previous filehandle was saved 2141 then it is no longer accessible. The saved filehandle can be 2142 restored as the current filehandle with the RESTOREFH operator. 2144 IMPLEMENTATION 2146 (see RESTOREFH) 2148 ERRORS 2150 NFS4ERR_SERVERFAULT 2152 Strawman NFS version 4 August 1998 2154 9.18. Procedure 17: PUTFH - Set current filehandle 2156 SYNOPSIS 2158 filehandle -> (cfh) 2160 ARGS 2162 filehandle: filehandle 2164 RESULTS 2166 (none) 2168 DESCRIPTION 2170 Replaces the current filehandle with the filehandle 2171 provided as an argument. If no filehandle has previously 2172 been installed as the current filehandle then root filehandle 2173 is assumed. If the length of the filehandle is zero, it is 2174 recognized by the server as a "public" filehandle. 2176 IMPLEMENTATION 2178 Commonly used as the first operator in any NFS request 2179 to set the context for following operations. 2181 ERRORS 2182 NFS4ERR_BADHANDLE 2183 NFS4ERR_SERVERFAULT 2185 Strawman NFS version 4 August 1998 2187 9.19. Procedure 18: PUTROOTFH - Set root filehandle 2189 SYNOPSIS 2191 - -> (cfh) 2193 ARGS 2195 (none) 2197 RESULTS 2199 (none) 2201 DESCRIPTION 2203 Replaces the current filehandle with the filehandle that 2204 represents the root of the server's namespace. From this 2205 filehandle a LOOKUP operation can locate any other filehandle on 2206 the server. This filehandle may be different from the "public" 2207 filehandle which may be associated with some other directory on 2208 the server. 2210 IMPLEMENTATION 2212 Commonly used as the first operator in any NFS request to set the 2213 context for following operations. 2215 ERRORS 2217 NFS4ERR_SERVERFAULT 2219 Strawman NFS version 4 August 1998 2221 9.20. Procedure 19: READ - Read from file 2223 SYNOPSIS 2225 (cfh), offset, count -> eof, data 2227 ARGS 2229 offset: uint64 2231 count: uint32 2233 RESULTS 2235 eof: bool 2237 data: opaque <> 2239 DESCRIPTION 2241 READ reads data from the file identified by the current 2242 filehandle. 2244 offset 2246 The position within the file at which the read is to begin. 2247 An offset of 0 means to read data starting at the beginning 2248 of the file. If offset is greater than or equal to the size 2249 of the file, the status, NFS4_OK, is returned with count set 2250 to 0 and eof set to TRUE, subject to access permissions 2251 checking. 2253 count 2255 The number of bytes of data that are to be read. If count is 2256 0, the READ will succeed and return 0 bytes of data, subject 2257 to access permissions checking. count must be less than or 2258 equal to the value of the rtmax for the file system that 2259 contains file. If greater, the server may return only rtmax 2260 bytes, resulting in a short read. 2262 If the operation is successful the results are: 2264 eof 2266 If the read ended at the end-of-file (formally, in a 2267 correctly formed READ request, if offset + count is equal to 2269 Strawman NFS version 4 August 1998 2271 the size of the file), eof is returned as TRUE; otherwise it 2272 is FALSE. A successful READ of an empty file will always 2273 return eof as TRUE. 2275 data 2277 The counted data read from the file. 2279 IMPLEMENTATION 2281 It is possible for the server to return fewer than count bytes of 2282 data. If the server returns less than the count requested and eof 2283 set to FALSE, the client should issue another READ to get the 2284 remaining data. A server may return less data than requested under 2285 several circumstances. The file may have been truncated by another 2286 client or perhaps on the server itself, changing the file size 2287 from what the requesting client believes to be the case. This 2288 would reduce the actual amount of data available to the client. It 2289 is possible that the server may back off the transfer size and 2290 reduce the read request return. Server resource exhaustion may 2291 also occur necessitating a smaller read return. 2293 If the file is locked the server will return an NFS4ERR_LOCKED 2294 error. Since the lock may be of short duration, the client may 2295 choose to retransmit the READ request (with exponential backoff) 2296 until the operation succeeds. 2298 ERRORS 2300 NFS4ERR_IO 2302 NFS4ERR_NXIO 2304 NFS4ERR_ACCES 2306 NFS4ERR_INVAL 2308 NFS4ERR_LOCKED 2310 NFS4ERR_SERVERFAULT 2312 Strawman NFS version 4 August 1998 2314 9.21. Procedure 20: READDIR - Read directory 2316 SYNOPSIS 2317 (cfh), cookie, dircount, maxcount, attrbits -> { cookie, filename, 2318 attrbits, attributes }... 2320 ARGS 2322 cookie: uint64 2324 This should be set to 0 in the first request to read the 2325 directory. On subsequent requests, it should be a cookie as 2326 returned by the server. 2328 dircount: uint32 2330 The maximum number of bytes of directory information 2331 returned. This number should not include the size of the 2332 attributes and file handle portions of the result. 2334 maxcount: uint32 2336 The maximum size of the result in bytes. The size must 2337 include all XDR overhead. The server is free to return less 2338 than count bytes of data. 2340 attrbits: bitmap 2342 The attributes to be returned for each directory entry. 2344 RESULTS 2346 A list of directory entries. Each entry contains: 2348 cookie: uint64 2350 A value recognized by the server as a "bookmark" into the 2351 directory. It may be an offset or an index into a table. 2352 Ideally, the cookie value should not change if the directory 2353 is modified. 2355 filename: utf8string; 2357 The name of the directory entry. 2359 attrbits: bitmap 2361 Strawman NFS version 4 August 1998 2363 A bitmap that indicates which attributes follow. Ideally 2364 this bitmap will be identical to the attribute bitmap in the 2365 arguments, i.e. the server returns everything the client 2366 asked for. However, the returned bitmap may be different if 2367 the server does not support the attribute or if the attribute 2368 is not valid for the filetype. 2370 Note: need to consider the file handle as an "attribute" 2371 that may be optionally returned. The concept of file handle 2372 as attribute might also be useful for the CREATE of a hard 2373 link. 2375 DESCRIPTION 2377 Procedure READDIR retrieves a variable number of entries from a 2378 file system directory and returns complete information about each 2379 entry along with information to allow the client to request 2380 additional directory entries in a subsequent READDIR. 2382 IMPLEMENTATION 2384 Issues that need to be understood for this procedure include 2385 increased cache flushing activity on the client (as new file 2386 handles are returned with names which are entered into caches) and 2387 over-the-wire overhead versus expected subsequent LOOKUP and 2388 GETATTR elimination. 2390 The dircount and maxcount fields are included as an optimization. 2391 Consider a READDIR call on a UNIX operating system implementation 2392 for 1048 bytes; the reply does not contain many entries because of 2393 the overhead due to attributes and file handles. An alternative is 2394 to issue a READDIR call for 8192 bytes and then only use the first 2395 1048 bytes of directory information. However, the server doesn't 2396 know that all that is needed is 1048 bytes of directory 2397 information (as would be returned by READDIR). It sees the 8192 2398 byte request and issues a VOP_READDIR for 8192 bytes. It then 2399 steps through all of those directory entries, obtaining attributes 2400 and file handles for each entry. When it encodes the result, the 2401 server only encodes until it gets 8192 bytes of results which 2402 include the attributes and file handles. Thus, it has done a 2403 larger VOP_READDIR and many more attribute fetches than it needed 2404 to. The ratio of the directory entry size to the size of the 2405 attributes plus the size of the file handle is usually at least 8 2406 to 1. The server has done much more work than it needed to. 2408 The solution to this problem is for the client to provide two 2409 counts to the server. The first is the number of bytes of 2411 Strawman NFS version 4 August 1998 2413 directory information that the client really wants, dircount. The 2414 second is the maximum number of bytes in the result, including the 2415 attributes and file handles, maxcount. Thus, the server will issue 2416 a VOP_READDIR for only the number of bytes that the client really 2417 wants to get, not an inflated number. This should help to reduce 2418 the size of VOP_READDIR requests on the server, thus reducing the 2419 amount of work done there, and to reduce the number of VOP_LOOKUP, 2420 VOP_GETATTR, and other calls done by the server to construct 2421 attributes and file handles. 2423 ERRORS 2425 NFS4ERR_IO 2427 NFS4ERR_ACCES 2429 NFS4ERR_NOTDIR 2431 NFS4ERR_BAD_COOKIE 2433 NFS4ERR_TOOSMALL 2435 NFS4ERR_NOTSUPP 2437 NFS4ERR_SERVERFAULT 2439 Strawman NFS version 4 August 1998 2441 9.22. Procedure 21: READLINK - Read symbolic link 2443 SYNOPSIS 2445 (cfh) -> linktext 2447 ARGS 2449 (none) 2451 RESULTS 2453 linktext: utf8string 2455 DESCRIPTION 2457 READLINK reads the data associated with a symbolic link. The data 2458 is a UTF-8 string that is opaque to the server. That is, whether 2459 created by an NFS client or created locally on the server, the 2460 data in a symbolic link is not interpreted when created, but is 2461 simply stored. 2463 IMPLEMENTATION 2465 A symbolic link is nominally a pointer to another file. The data 2466 is not necessarily interpreted by the server, just stored in the 2467 file. It is possible for a client implementation to store a path 2468 name that is not meaningful to the server operating system in a 2469 symbolic link. A READLINK operation returns the data to the 2470 client for interpretation. If different implementations want to 2471 share access to symbolic links, then they must agree on the 2472 interpretation of the data in the symbolic link. 2474 The READLINK operation is only allowed on objects of type, NFLNK. 2475 The server should return the error, NFS4ERR_INVAL, if the object 2476 is not of type, NFLNK. 2478 ERRORS 2480 NFS4ERR_IO 2482 NFS4ERR_INVAL 2484 NFS4ERR_ACCES 2486 NFS4ERR_NOTSUPP 2488 Strawman NFS version 4 August 1998 2490 NFS4ERR_SERVERFAULT 2492 Strawman NFS version 4 August 1998 2494 9.23. Procedure 22: REMOVE - Remove filesystem object 2496 SYNOPSIS 2498 (cfh), filename -> - 2500 ARGS 2502 entryname: utf8string 2504 RESULTS 2506 (none) 2508 DESCRIPTION 2510 REMOVE removes (deletes) a directory entry named by filename from 2511 the directory corresponding to the current filehandle. If the 2512 entry in the directory was the last reference to the corresponding 2513 file system object, the object may be destroyed. 2515 IMPLEMENTATION 2517 NFS versions 2 and 3 required a different operator RMDIR for 2518 directory removal. NFS version 4 REMOVE can be used to delete any 2519 directory entry independent of its filetype. 2521 The concept of last reference is server specific. However, if the 2522 nlink field in the previous attributes of the object had the value 2523 1, the client should not rely on referring to the object via a 2524 file handle. Likewise, the client should not rely on the resources 2525 (disk space, directory entry, and so on.) formerly associated with 2526 the object becoming immediately available. Thus, if a client needs 2527 to be able to continue to access a file after using REMOVE to 2528 remove it, the client should take steps to make sure that the file 2529 will still be accessible. The usual mechanism used is to use 2530 RENAME to rename the file from its old name to a new hidden name. 2532 ERRORS 2534 NFS4ERR_NOENT 2536 NFS4ERR_IO 2538 NFS4ERR_ACCES 2540 NFS4ERR_NOTDIR 2542 Strawman NFS version 4 August 1998 2544 NFS4ERR_NAMETOOLONG 2546 NFS4ERR_ROFS 2548 NFS4ERR_NOTEMPTY 2550 NFS4ERR_SERVERFAULT 2552 Strawman NFS version 4 August 1998 2554 9.24. Procedure 23: RENAME - Rename directory entry 2556 SYNOPSIS 2558 (cfh), oldname, newdir, newname -> - 2560 ARGS 2562 oldname: utf8string 2564 newdir: filehandle 2566 newname: utf8string 2568 RESULTS 2570 status: uint32 2572 DESCRIPTION 2574 RENAME renames the directory identified by oldname in the 2575 directory corresponding to the current filehandle to newname in 2576 directory newdir. The operation is required to be atomic to the 2577 client. Source and target directories must reside on the same file 2578 system on the server. 2580 If the directory, newdir, already contains an entry with the name, 2581 newname, the source object must be compatible with the target: 2582 either both are non-directories or both are directories and the 2583 target must be empty. If compatible, the existing target is 2584 removed before the rename occurs. If they are not compatible or if 2585 the target is a directory but not empty, the server should return 2586 the error, NFS4ERR_EXIST. 2588 IMPLEMENTATION 2590 The RENAME operation must be atomic to the client. The statement 2591 "source and target directories must reside on the same file system 2592 on the server" means that the fsid fields in the attributes for 2593 the directories are the same. If they reside on different file 2594 systems, the error, NFS4ERR_XDEV, is returned. Even though the 2595 operation is atomic, the status, NFS4ERR_MLINK, may be returned if 2596 the server used a "unlink/link/unlink" sequence internally. 2598 A file handle may or may not become stale on a rename. However, 2599 server implementors are strongly encouraged to attempt to keep 2600 file handles from becoming stale in this fashion. 2602 Strawman NFS version 4 August 1998 2604 On some servers, the filenames, "." and "..", are illegal as 2605 either oldname or newname. In addition, neither oldname nor 2606 newname can be an alias for the source directory. These servers 2607 will return the error, NFS4ERR_INVAL, in these cases. 2609 If oldname and newname both refer to the same file (they might be 2610 hard links of each other), then RENAME should perform no action 2611 and return success. 2613 ERRORS 2615 NFS4ERR_NOENT 2617 NFS4ERR_IO 2619 NFS4ERR_ACCES 2621 NFS4ERR_EXIST 2623 NFS4ERR_XDEV 2625 NFS4ERR_NOTDIR 2627 NFS4ERR_ISDIR 2629 NFS4ERR_INVAL 2631 NFS4ERR_NOSPC 2633 NFS4ERR_ROFS 2635 NFS4ERR_MLINK 2637 NFS4ERR_NAMETOOLONG 2639 NFS4ERR_NOTEMPTY 2641 NFS4ERR_DQUOT 2643 NFS4ERR_NOTSUPP 2645 NFS4ERR_SERVERFAULT 2647 Strawman NFS version 4 August 1998 2649 9.25. Procedure 24: SETATTR - Set attributes 2651 SYNOPSIS 2653 (cfh), attrbits, attrvals -> - 2655 ARGS 2657 attrbits: bitmap 2659 attrvals 2661 DESCRIPTION 2663 Procedure SETATTR changes one or more of the attributes of a file 2664 system object on the server. The new attributes are specified with 2665 a bitmap and the attributes that follow the bitmap in bit order. 2667 IMPLEMENTATION 2669 The file size attribute is used to request changes to the size of 2670 a file. A value of 0 causes the file to be truncated, a value less 2671 than the current size of the file causes data from new size to the 2672 end of the file to be discarded, and a size greater than the 2673 current size of the file causes logically zeroed data bytes to be 2674 added to the end of the file. Servers are free to implement this 2675 using holes or actual zero data bytes. Clients should not make any 2676 assumptions regarding a server's implementation of this feature, 2677 beyond that the bytes returned will be zeroed. Servers must 2678 support extending the file size via SETATTR. 2680 SETATTR is not guaranteed atomic. A failed SETATTR may partially 2681 change a file's attributes. 2683 Changing the size of a file with SETATTR indirectly changes the 2684 mtime. A client must account for this as size changes can result 2685 in data deletion. 2687 If server and client times differ, programs that compare client 2688 time to file times can break. A time maintenance protocol should 2689 be used to limit client/server time skew. 2691 If the server cannot successfully set all the attributes it must 2692 return an NFS4ERR_INVAL error. An error may be returned if the 2693 server can not store a uid or gid in its own representation of 2694 uids or gids, respectively. If the server can only support 32 bit 2695 offsets and sizes, a SETATTR request to set the size of a file to 2697 Strawman NFS version 4 August 1998 2699 larger than can be represented in 32 bits will be rejected with 2700 this same error. 2702 ERRORS 2704 NFS4ERR_PERM 2706 NFS4ERR_IO 2708 NFS4ERR_ACCES 2710 NFS4ERR_INVAL 2712 NFS4ERR_NOSPC 2714 NFS4ERR_ROFS 2716 NFS4ERR_DQUOT 2718 NFS4ERR_SERVERFAULT 2720 Strawman NFS version 4 August 1998 2722 9.26. Procedure 25: VERIFY - Verify attributes same 2724 SYNOPSIS 2726 (cfh), attrbits, attrvals -> - 2728 ARGS 2730 attrbits: bitmap 2732 attrvals 2734 RESULTS 2736 (none) 2738 DESCRIPTION 2740 This operation is used to verify that attributes have a value 2741 assumed by the client before proceeding with following operations 2742 in the compound request. For instance, a VERIFY can be used to 2743 make sure that the file size has not changed for an append-mode 2744 write: 2746 1. PUTFH 0x0123456 2747 2. VERIFY attrbits attrs 2748 3. WRITE 450328 4096 2750 If the attributes are not as expected, then the request fails and 2751 the data is not appended to the file. 2753 IMPLEMENTATION 2755 ERRORS 2757 Strawman NFS version 4 August 1998 2759 9.27. Procedure 26: WRITE - Write to file 2761 SYNOPSIS 2763 (cfh), offset, count, stability, data -> count, committed, 2764 verifier 2766 ARGS 2768 offset: uint64 2770 count: uint32 2772 stability: uint32 2774 data: opaque 2776 RESULTS 2778 count: uint32 2780 committed: uint32 2782 verifier: uint32 2784 DESCRIPTION 2786 Write data to the file identified by the current filehandle. 2787 Arguments are as follows: 2789 offset 2791 The position within the file at which the write is to begin. 2792 An offset of 0 means to write data starting at the beginning 2793 of the file. 2795 count 2797 The number of bytes of data to be written. If count is 0, the 2798 WRITE will succeed and return a count of 0, barring errors 2799 due to permissions checking. The size of data must be less 2800 than or equal to the value of the wtmax attribute for the 2801 filesystem that contains file. If greater, the server may 2802 write only wtmax bytes, resulting in a short write. 2804 stability 2806 Strawman NFS version 4 August 1998 2808 If stable is FILE_SYNC, the server must commit the data 2809 written plus all file system metadata to stable storage 2810 before returning results. This corresponds to the NFS version 2811 2 protocol semantics. Any other behavior constitutes a 2812 protocol violation. If stable is DATA_SYNC, then the server 2813 must commit all of the data to stable storage and enough of 2814 the metadata to retrieve the data before returning. The 2815 server implementor is free to implement DATA_SYNC in the same 2816 fashion as FILE_SYNC, but with a possible performance drop. 2817 If stable is UNSTABLE, the server is free to commit any part 2818 of the data and the metadata to stable storage, including all 2819 or none, before returning a reply to the client. There is no 2820 guarantee whether or when any uncommitted data will 2821 subsequently be committed to stable storage. The only 2822 guarantees made by the server are that it will not destroy 2823 any data without changing the value of verf and that it will 2824 not commit the data and metadata at a level less than that 2825 requested by the client. 2827 data 2829 The data to be written to the file. 2831 If the operation is successful the following results are returned: 2833 count 2835 The number of bytes of data written to the file. The server 2836 may write fewer bytes than requested. If so, the actual 2837 number of bytes written starting at location, offset, is 2838 returned. 2840 committed 2842 The server should return an indication of the level of 2843 commitment of the data and metadata via committed. If the 2844 server committed all data and metadata to stable storage, 2845 committed should be set to FILE_SYNC. If the level of 2846 commitment was at least as strong as DATA_SYNC, then 2847 committed should be set to DATA_SYNC. Otherwise, committed 2848 must be returned as UNSTABLE. If stable was FILE_SYNC, then 2849 committed must also be FILE_SYNC: anything else constitutes a 2850 protocol violation. If stable was DATA_SYNC, then committed 2851 may be FILE_SYNC or DATA_SYNC: anything else constitutes a 2852 protocol violation. If stable was UNSTABLE, then committed 2853 may be either FILE_SYNC, DATA_SYNC, or UNSTABLE. 2855 verifier 2857 Strawman NFS version 4 August 1998 2859 This is a cookie that the client can use to determine whether 2860 the server has changed state between a call to WRITE and a 2861 subsequent call to either WRITE or COMMIT. This cookie must 2862 be consistent during a single instance of the NFS version 4 2863 protocol service and must be unique between instances of the 2864 NFS version 4 protocol server, where uncommitted data may be 2865 lost. 2867 If a client writes data to the server with the stable argument set 2868 to UNSTABLE and the reply yields a committed response of DATA_SYNC 2869 or UNSTABLE, the client will follow up some time in the future 2870 with a COMMIT operation to synchronize outstanding asynchronous 2871 data and metadata with the server's stable storage, barring client 2872 error. It is possible that due to client crash or other error that 2873 a subsequent COMMIT will not be received by the server. 2875 IMPLEMENTATION 2877 It is possible for the server to write fewer than count bytes of 2878 data. In this case, the server should not return an error unless 2879 no data was written at all. If the server writes less than count 2880 bytes, the client should issue another WRITE to write the 2881 remaining data. 2883 It is assumed that the act of writing data to a file will cause 2884 the mtime of the file to be updated. However, the mtime of the 2885 file should not be changed unless the contents of the file are 2886 changed. Thus, a WRITE request with count set to 0 should not 2887 cause the mtime of the file to be updated. 2889 The definition of stable storage has been historically a point of 2890 contention. The following expected properties of stable storage 2891 may help in resolving design issues in the implementation. Stable 2892 storage is persistent storage that survives: 2894 1. Repeated power failures. 2895 2. Hardware failures (of any board, power supply, etc.). 2896 3. Repeated software crashes, including reboot cycle. 2898 This definition does not address failure of the stable storage 2899 module itself. 2901 The verifier, is defined to allow a client to detect different 2902 instances of an NFS version 4 protocol server over which cached, 2903 uncommitted data may be lost. In the most likely case, the 2904 verifier allows the client to detect server reboots. This 2906 Strawman NFS version 4 August 1998 2908 information is required so that the client can safely determine 2909 whether the server could have lost cached data. If the server 2910 fails unexpectedly and the client has uncommitted data from 2911 previous WRITE requests (done with the stable argument set to 2912 UNSTABLE and in which the result committed was returned as 2913 UNSTABLE as well) it may not have flushed cached data to stable 2914 storage. The burden of recovery is on the client and the client 2915 will need to retransmit the data to the server. 2917 A suggested verifier would be to use the time that the server was 2918 booted or the time the server was last started (if restarting the 2919 server without a reboot results in lost buffers). 2921 The committed field in the results allows the client to do more 2922 effective caching. If the server is committing all WRITE requests 2923 to stable storage, then it should return with committed set to 2924 FILE_SYNC, regardless of the value of the stable field in the 2925 arguments. A server that uses an NVRAM accelerator may choose to 2926 implement this policy. The client can use this to increase the 2927 effectiveness of the cache by discarding cached data that has 2928 already been committed on the server. 2930 Some implementations may return NFS4ERR_NOSPC instead of 2931 NFS4ERR_DQUOT when a user's quota is exceeded. 2933 ERRORS 2935 NFS4ERR_IO 2937 NFS4ERR_ACCES 2939 NFS4ERR_FBIG 2941 NFS4ERR_DQUOT 2943 NFS4ERR_NOSPC 2945 NFS4ERR_ROFS 2947 NFS4ERR_INVAL 2949 NFS4ERR_LOCKED 2951 NFS4ERR_SERVERFAULT 2953 Strawman NFS version 4 August 1998 2955 9.28. Procedure 27: SECINFO - Obtain Available Security 2957 SYNOPSIS 2959 (cfh), filename -> { secinfo } 2961 ARGS 2963 filename: utf8string 2965 RESULTS 2967 secinfo: secinfo 2968 This is a link list of security flavors available for the 2969 supplied file handle and filename. 2971 DESCRIPTION 2973 This procedure is used by the client to obtain a list of valid RPC 2974 authentication flavors for a specific file handle, file name pair. 2975 For the flavors, AUTH_NONE, AUTH_SYS, AUTH_DH, and AUTH_KRB4 no 2976 additional security information is returned. For a return value 2977 of AUTH_RPCSEC_GSS, a security triple is returned that contains 2978 the mechanism object id (as defined in [RFC2078]), the quality of 2979 protection (as defined in [RFC 2078]) and the service type (as 2980 defined in [RFC2203]). It is possible for SECINFO to return 2981 multiple entries with flavor equal to AUTH_RPCSEC_GSS with 2982 different security triple values. 2984 IMPLEMENTATION 2986 This procedure is expected to be used by the NFS client when the 2987 error value of NFS4ERR_WRONGSEC is returned from another NFS 2988 procedure. This signifies to the client that the server's 2989 security policy is different from what the client is currently 2990 using. At this point, the client is expected to obtain a list of 2991 possible security flavors and choose what best suits its policies. 2993 ERRORS 2995 NFS4ERR_NOENT 2997 NFS4ERR_IO 2999 NFS4ERR_ACCES 3001 NFS4ERR_NAMETOOLONG 3003 Strawman NFS version 4 August 1998 3005 NFS4ERR_STALE 3007 NFS4ERR_SERVERFAULT 3009 NFS4ERR_FHEXPIRED 3011 NFS4ERR_WRONGSEC 3013 Strawman NFS version 4 August 1998 3015 10. Locking notes 3017 10.1. Short and long leases 3019 The usual lease trade-offs apply: short leases are good for fast 3020 server recovery at a cost of increased LOCKX requests, though this 3021 may not be a factor if we can take advantage of compound requests to 3022 piggyback LOCKX on normal read and write requests. If the client is 3023 not actively doing I/O, perhaps a user editing a locked file, then 3024 the lOCKX requests become more obvious. 3026 Longer leases are certainly kinder and gentler to large internet 3027 servers trying to handle huge numbers of clients. LOCKX requests drop 3028 in direct proportion to the lease time. The disadvantages of long 3029 leases are slower server recover after crash (server must wait for 3030 leases to expire and grace period before granting new lock requests) 3031 and increased file contention (if client fails to transmit an unlock 3032 request then server must wait for lease expiry before granting new 3033 locks). 3035 Assuming that locks are held for very short periods (msec), that 3036 unlock requests usually get through, that there is usually very 3037 little lock contention, I'd recommend long leases to keep LOCKX 3038 requests to a minimum, i.e. leases of one or two minutes. This seems 3039 appropriate for an Internet scale - and no problem on Intranets. 3041 10.2. Clocks and leases 3043 To avoid the need for synchronized clocks, lease times are granted by 3044 the server as a time delta, though there is a requirement that the 3045 client and server clocks do not drift exessively over the duration of 3046 the lock. There is also the issue of propagation delay across the 3047 network which could easily be several hundred milliseconds across the 3048 Internet as well as the possibility that requests will be lost and 3049 need to be retransmitted. 3051 To take propagation delay into account, the client should subtract a 3052 it from lease times, e.g. if if the client estimates the one-way 3053 propagation delay as 200 msec, then it can assume that the lease is 3054 already 200 msec old when it gets it. In addition, it'll take 3055 another 200 msec to get a response back to the server. So the client 3056 must send a lock renewal or write data back to the server 400 msec 3057 before the lease would expire. 3059 The client could measure propagation delay with reasonable accuracy 3060 by measuring the round-trip time for lock extensions assuming that 3061 there's not much server processing overhead in an extension. 3063 Strawman NFS version 4 August 1998 3065 10.3. Locks and lease times 3067 Lock requests do not contain desired lease times. The server 3068 allocates leases with no information from the client. The assumption 3069 here is that the client really has no idea of just how long the lock 3070 will be required. If a scenario can be found where a hint from the 3071 client as to the maximum lease time desired would be useful, then 3072 this feature could be added to lock requests. 3074 10.4. Lease scalability 3076 Read locks will be vastly more popular than write locks and will be 3077 popular for client caching. A server might easily have a hundred 3078 thousand concurrent read locks on a single file. The server doesn't 3079 need to store individual lease times for each client - only the 3080 longest lease associated with each locked file. 3082 10.5. Rejecting write locks and denial of service 3084 Unrestricted use of locking could certainly asking for denial of 3085 service attacks. There's an implicit assumption here that attempts 3086 to set write locks will be rejected if the client does not have write 3087 permission for the file. Similarly for read locks if the client has 3088 no read permission. 3090 10.6. Locking of directories and other meta-files 3092 A question: should directories and/or other filesystem objects like 3093 symbolic links be lockable ? Clients will want to cache whole 3094 directories. It would be nice to have consistent directory caches, 3095 but it would require that any client creating a new file get a write 3096 lock on the directory and be prepared to handle lock denial. Is the 3097 weak cache consistency that we currently have for directories 3098 acceptable ? I think perhaps it is - given the expense of doing full 3099 consistency on an Internet scale. 3101 10.7. Proxy servers and leases 3103 Proxy servers. There is some interest in having NFS V4 support 3104 caching proxies. Support for proxy caching is a requirement if 3105 servers are to handle large numbers of clients - clients that may 3106 have little or no ability to cache on their own. How could proxy 3107 servers use lease-based locking ? 3109 10.8. Archive updates and lease time adjustment 3111 Regularly-updated archives. It is common for FTP and HTTP servers on 3112 the Internet to be updated at regularly scheduled intervals, e.g. on 3114 Strawman NFS version 4 August 1998 3116 the hour, daily, or weekly. These servers could grant extremely long 3117 leases that get progressively shorter as the update time draws near. 3118 Clients get to cache efficiently, network and server load is vastly 3119 reduced, and new data is available as soon as it is updated. The 3120 lease times might be randomly skewed across clients to spread the 3121 update load. These servers may choose to assign a blanket lease time 3122 for the entire server or for an entire filesystem. 3124 10.9. Locking and the new latency 3126 Latency caused by locking. If a client wants to update a file then 3127 it will have to wait until the leases on read locks have expired. If 3128 the leases are of the order of 60 seconds or several minutes then the 3129 client (and end-user) may be blocked for a while. This is unfamiliar 3130 for current NFS users who are not bothered by mandatory locking - but 3131 it could be an issue if we decide we like the caching benefits. A 3132 similar problem exists for clients that wish to read a file that is 3133 write locked. The read-lock case is likely to be more common if 3134 read-locking is used to protect cached data on the client. 3136 Strawman NFS version 4 August 1998 3138 11. NFS Version 4 RPC definition file 3140 /* 3141 * nfs_prot.x 3142 * 3143 */ 3145 %#pragma ident "@(#)nfs_prot.x 1.24 98/08/06" 3147 /* 3148 * Sizes 3149 */ 3150 const NFS4_FHSIZE = 128; 3151 const NFS4_CREATEVERFSIZE = 8; 3153 /* 3154 * Timeval 3155 */ 3156 struct nfstime4 { 3157 int64_t seconds; 3158 uint32_t nseconds; 3159 }; 3161 struct specdata4 { 3162 uint32_t specdata1; 3163 uint32_t specdata2; 3164 }; 3166 /* 3167 * Basic data types 3168 */ 3169 typedef opaque utf8string<>; 3170 typedef uint64_t offset4; 3171 typedef uint32_t count4; 3172 typedef uint32_t length4; 3173 typedef uint32_t writeverf4; 3174 typedef opaque createverf4[NFS4_CREATEVERFSIZE]; 3175 typedef utf8string filename4; 3176 typedef uint64_t nfs_lockid4; 3177 typedef uint32_t nfs_lease4; 3178 typedef uint32_t nfs_lockstate4; 3179 typedef uint64_t nfs_cookie4; 3180 typedef utf8string linktext4; 3181 typedef opaque sec_oid4<>; 3182 typedef uint32_t qop4; 3184 typedef uint32_t fattr4_type; 3185 typedef uint32_t fattr4_mode; 3187 Strawman NFS version 4 August 1998 3189 typedef uint32_t fattr4_accessbits; 3190 typedef uint32_t fattr4_nlink; 3191 typedef utf8string fattr4_uid; 3192 typedef utf8string fattr4_gid; 3193 typedef uint64_t fattr4_size; 3194 typedef uint64_t fattr4_used; 3195 typedef specdata4 fattr4_rdev; 3196 typedef uint64_t fattr4_fsid; 3197 typedef uint64_t fattr4_fileid; 3198 typedef nfstime4 fattr4_atime; 3199 typedef nfstime4 fattr4_mtime; 3200 typedef nfstime4 fattr4_ctime; 3201 typedef uint32_t fattr4_rtmax; 3202 typedef uint32_t fattr4_rtpref; 3203 typedef uint32_t fattr4_rtmult; 3204 typedef uint32_t fattr4_wtmax; 3205 typedef uint32_t fattr4_wtpref; 3206 typedef uint32_t fattr4_wtmult; 3207 typedef uint32_t fattr4_dtpref; 3208 typedef uint64_t fattr4_maxfilesize; 3209 typedef uint64_t fattr4_change; 3210 typedef nfstime4 fattr4_time_delta; 3211 typedef uint32_t fattr4_properties; 3212 typedef uint32_t fattr4_linkmax; 3213 typedef uint32_t fattr4_name_max; 3215 /* 3216 * Error status 3217 */ 3218 enum nfsstat4 { 3219 NFS4_OK = 0, 3220 NFS4ERR_PERM = 1, 3221 NFS4ERR_NOENT = 2, 3222 NFS4ERR_IO = 5, 3223 NFS4ERR_NXIO = 6, 3224 NFS4ERR_ACCES = 13, 3225 NFS4ERR_EXIST = 17, 3226 NFS4ERR_XDEV = 18, 3227 NFS4ERR_NODEV = 19, 3228 NFS4ERR_NOTDIR = 20, 3229 NFS4ERR_ISDIR = 21, 3230 NFS4ERR_INVAL = 22, 3231 NFS4ERR_FBIG = 27, 3232 NFS4ERR_NOSPC = 28, 3233 NFS4ERR_ROFS = 30, 3234 NFS4ERR_MLINK = 31, 3235 NFS4ERR_NAMETOOLONG = 63, 3236 NFS4ERR_NOTEMPTY = 66, 3238 Strawman NFS version 4 August 1998 3240 NFS4ERR_DQUOT = 69, 3241 NFS4ERR_STALE = 70, 3242 NFS4ERR_BADHANDLE = 10001, 3243 NFS4ERR_NOT_SYNC = 10002, 3244 NFS4ERR_BAD_COOKIE = 10003, 3245 NFS4ERR_NOTSUPP = 10004, 3246 NFS4ERR_TOOSMALL = 10005, 3247 NFS4ERR_SERVERFAULT = 10006, 3248 NFS4ERR_BADTYPE = 10007, 3249 NFS4ERR_JUKEBOX = 10008, 3250 NFS4ERR_SAME = 10009, 3251 NFS4ERR_DENIED = 10010, 3252 NFS4ERR_EXPIRED = 10011, 3253 NFS4ERR_LOCKED = 10012 3254 }; 3256 enum rpc_flavor4 { 3257 AUTH_NONE = 0, 3258 AUTH_SYS = 1, 3259 AUTH_DH = 2, 3260 AUTH_KRB4 = 3, 3261 AUTH_RPCSEC_GSS = 4 3262 }; 3264 /* 3265 * From RFC 2203 3266 */ 3267 enum rpc_gss_svc_t { 3268 RPC_GSS_SVC_NONE = 1, 3269 RPC_GSS_SVC_INTEGRITY = 2, 3270 RPC_GSS_SVC_PRIVACY = 3 3271 }; 3273 /* 3274 * LOCKX lock type 3275 */ 3276 enum lockx_locktype { 3277 READLOCK = 1, 3278 WRITELOCK = 2 3279 }; 3281 /* 3282 * File access handle 3283 */ 3284 struct nfs_fh4 { 3285 opaque data; 3286 }; 3288 Strawman NFS version 4 August 1998 3290 /* 3291 * File types 3292 */ 3293 enum ftype4 { 3294 NF4REG = 1, 3295 NF4DIR = 2, 3296 NF4BLK = 3, 3297 NF4CHR = 4, 3298 NF4LNK = 5, 3299 NF4SOCK = 6, 3300 NF4FIFO = 7 3301 }; 3303 const FATTR4_TYPE = 1; 3304 const FATTR4_MODE = 2; 3305 const FATTR4_ACCESSBITS = 3; 3306 const FATTR4_NLINK = 4; 3307 const FATTR4_UID = 5; 3308 const FATTR4_GID = 6; 3309 const FATTR4_SIZE = 7; 3310 const FATTR4_USED = 8; 3311 const FATTR4_RDEV = 9; 3312 const FATTR4_FSID = 10; 3313 const FATTR4_FILEID = 11; 3314 const FATTR4_ATIME = 12; 3315 const FATTR4_MTIME = 13; 3316 const FATTR4_CTIME = 14; 3317 const FATTR4_RTMAX = 15; 3318 const FATTR4_RTPREF = 16; 3319 const FATTR4_RTMULT = 17; 3320 const FATTR4_WTMAX = 18; 3321 const FATTR4_WTPREF = 19; 3322 const FATTR4_WTMULT = 20; 3323 const FATTR4_DTPREF = 21; 3324 const FATTR4_MAXFILESIZE = 22; 3325 const FATTR4_TIME_DELTA = 23; 3326 const FATTR4_PROPERTIES = 24; 3327 const FATTR4_LINKMAX = 25; 3328 const FATTR4_NAME_MAX = 26; 3329 const FATTR4_NO_TRUNC = 27; 3330 const FATTR4_CHOWN_RESTRICTED = 28; 3331 const FATTR4_CASE_INSENSITIVE = 29; 3332 const FATTR4_CASE_PRESERVING = 30; 3334 /* 3335 * fattr4_properties bits 3336 */ 3337 const FSF_LINK = 0x00000001; 3339 Strawman NFS version 4 August 1998 3341 const FSF_SYMLINK = 0x00000002; 3342 const FSF_HOMOGENEOUS = 0x00000004; 3343 const FSF_CANSETTIME = 0x00000008; 3344 const FSF_NOTRUNC = 0x00000010; 3345 const FSF_CHOWN_RESTRICTED = 0x00000020; 3346 const FSF_CASE_INSENSITIVE = 0x00000040; 3347 const FSF_CASE_PRESERVING = 0x00000080; 3349 struct bitmap4 { 3350 uint32_t bits<>; 3351 }; 3353 struct attrlist { 3354 opaque attrs<>; 3355 }; 3357 struct fattr4 { 3358 bitmap4 attrmask; 3359 attrlist attr_vals; 3360 }; 3362 /* 3363 * ACCESS: Check access permission 3364 */ 3365 const ACCESS4_READ = 0x0001; 3366 const ACCESS4_LOOKUP = 0x0002; 3367 const ACCESS4_MODIFY = 0x0004; 3368 const ACCESS4_EXTEND = 0x0008; 3369 const ACCESS4_DELETE = 0x0010; 3370 const ACCESS4_EXECUTE = 0x0020; 3372 struct ACCESS4args { 3373 uint32_t access; 3374 }; 3376 struct ACCESS4resok { 3377 uint32_t access; 3378 }; 3380 union ACCESS4res switch (nfsstat4 status) { 3381 case NFS4_OK: 3382 ACCESS4resok resok; 3383 default: 3384 void; 3385 }; 3387 /* 3388 * COMMIT: Commit cached data on server to stable storage 3390 Strawman NFS version 4 August 1998 3392 */ 3393 struct COMMIT4args { 3394 offset4 offset; 3395 count4 count; 3396 }; 3398 struct COMMIT4resok { 3399 writeverf4 verf; 3400 }; 3402 union COMMIT4res switch (nfsstat4 status) { 3403 case NFS4_OK: 3404 COMMIT4resok resok; 3405 default: 3406 void; 3407 }; 3409 /* 3410 * CREATE: Create a file 3411 */ 3412 enum createmode4 { 3413 UNCHECKED = 0, 3414 GUARDED = 1, 3415 EXCLUSIVE = 2 3416 }; 3418 union createhow4 switch (createmode4 mode) { 3419 case UNCHECKED: 3420 case GUARDED: 3421 fattr4 createattrs; 3422 case EXCLUSIVE: 3423 createverf4 verf; 3424 }; 3426 struct CREATE4args { 3427 filename4 name; 3428 ftype4 objtype; 3429 createhow4 how; 3430 }; 3432 union CREATE3res switch (nfsstat4 status) { 3433 case NFS4_OK: 3434 void; 3435 default: 3436 void; 3437 }; 3439 Strawman NFS version 4 August 1998 3441 /* 3442 * GETATTR: Get file attributes 3443 */ 3444 struct GETATTR4args { 3445 bitmap4 attr_request; 3446 }; 3448 struct GETATTR4resok { 3449 fattr4 obj_attributes; 3450 }; 3452 union GETATTR4res switch (nfsstat4 status) { 3453 case NFS4_OK: 3454 GETATTR4resok resok; 3455 default: 3456 void; 3457 }; 3459 /* 3460 * GETFH: Get current filehandle 3461 */ 3462 struct GETFH4resok { 3463 nfs_fh4 object; 3464 }; 3466 union GETFH4res switch (nfsstat4 status) { 3467 case NFS4_OK: 3468 GETFH4resok resok; 3469 default: 3470 void; 3471 }; 3473 /* 3474 * LINK: Create link to an object 3475 */ 3476 struct LINK4args { 3477 nfs_fh4 dir; 3478 filename4 newname; 3479 }; 3481 union LINK4res switch (nfsstat4 status) { 3482 case NFS4_OK: 3483 void; 3484 default: 3485 void; 3486 }; 3488 /* 3490 Strawman NFS version 4 August 1998 3492 * LOCKR: Create a read lock on a file 3493 */ 3494 struct LOCKR4args { 3495 nfs_lockid4 id; 3496 offset4 offset; 3497 length4 length; 3498 }; 3500 struct LOCKR4resok { 3501 nfs_lease4 lease; 3502 }; 3504 union LOCKR4res switch (nfsstat4 status) { 3505 case NFS4_OK: 3506 LOCKR4resok resok; 3507 default: 3508 void; 3509 }; 3511 /* 3512 * LOCKW: Create a write lock 3513 */ 3514 struct LOCKW4args { 3515 nfs_lockid4 id; 3516 offset4 offset; 3517 length4 length; 3518 }; 3520 struct LOCKW4resok { 3521 nfs_lease4 lease; 3522 }; 3524 union LOCKW4res switch (nfsstat4 status) { 3525 case NFS4_OK: 3526 LOCKW4resok resok; 3527 default: 3528 void; 3529 }; 3531 /* 3532 * LOCKT: Test for lock 3533 */ 3534 struct LOCKT4args { 3535 offset4 offset; 3536 length4 length; 3537 }; 3539 Strawman NFS version 4 August 1998 3541 struct LOCKT4resok { 3542 nfs_lockstate4 lease; 3543 }; 3545 union LOCKT4res switch (nfsstat4 status) { 3546 case NFS4_OK: 3547 LOCKT4resok resok; 3548 default: 3549 void; 3550 }; 3552 /* 3553 * LOCKX: validate and extend lock 3554 */ 3555 struct LOCKX4args { 3556 nfs_lockid4 id; 3557 offset4 offset; 3558 length4 length; 3559 lockx_locktype locktype; 3560 }; 3562 struct LOCKX4resok { 3563 nfs_lockstate4 lease; 3564 }; 3566 union LOCKX4res switch (nfsstat4 status) { 3567 case NFS4_OK: 3568 LOCKX4resok resok; 3569 default: 3570 void; 3571 }; 3573 /* 3574 * LOCKU: Unlock file 3575 */ 3576 struct LOCKU4args { 3577 nfs_lockid4 id; 3578 offset4 offset; 3579 length4 length; 3580 }; 3582 union LOCKU4res switch (nfsstat4 status) { 3583 case NFS4_OK: 3584 void; 3585 default: 3586 void; 3587 }; 3589 Strawman NFS version 4 August 1998 3591 /* 3592 * LOOKUP: Lookup filename 3593 */ 3594 struct LOOKUP4args { 3595 filename4 filenames<>; 3596 }; 3598 union LOOKUP4res switch (nfsstat4 status) { 3599 case NFS4_OK: 3600 void; 3601 default: 3602 void; 3603 }; 3605 /* 3606 * LOOKUPP: Lookup parent directory 3607 */ 3608 union LOOKUPP4res switch (nfsstat4 status) { 3609 case NFS4_OK: 3610 void; 3611 default: 3612 void; 3613 }; 3615 /* 3616 * NVERIFY: Verify attributes different 3617 */ 3618 struct NVERIFY4args { 3619 bitmap4 attr_request; 3620 fattr4 obj_attributes; 3621 }; 3623 union NVERIFY4res switch (nfsstat4 status) { 3624 case NFS4_OK: 3625 void; 3626 default: 3627 void; 3628 }; 3630 /* 3631 * RESTOREFH: Restore saved filehandle 3632 */ 3634 union RESTOREFH4res switch (nfsstat4 status) { 3635 case NFS4_OK: 3636 void; 3637 default: 3638 void; 3640 Strawman NFS version 4 August 1998 3642 }; 3644 /* 3645 * SAVEFH: Save current filehandle 3646 */ 3647 union SAVEFH4res switch (nfsstat4 status) { 3648 case NFS4_OK: 3649 void; 3650 default: 3651 void; 3652 }; 3654 /* 3655 * PUTFH: Set current filehandle 3656 */ 3657 struct PUTFH4args { 3658 nfs_fh4 object; 3659 }; 3661 union PUTFH4res switch (nfsstat4 status) { 3662 case NFS4_OK: 3663 void; 3664 default: 3665 void; 3666 }; 3668 /* 3669 * PUTROOTFH: Set root filehandle 3670 */ 3671 union PUTROOTFH4res switch (nfsstat4 status) { 3672 case NFS4_OK: 3673 void; 3674 default: 3675 void; 3676 }; 3678 /* 3679 * READ: Read from file 3680 */ 3681 struct READ4args { 3682 offset4 offset; 3683 count4 count; 3684 }; 3686 struct READ4resok { 3687 bool eof; 3688 opaque data<>; 3689 }; 3691 Strawman NFS version 4 August 1998 3693 union READ4res switch (nfsstat4 status) { 3694 case NFS4_OK: 3695 READ4resok resok; 3696 default: 3697 void; 3698 }; 3700 /* 3701 * READDIR: Read directory 3702 */ 3703 struct READDIR4args { 3704 nfs_cookie4 cookie; 3705 count4 dircount; 3706 count4 maxcount; 3707 bitmap4 attr_request; 3709 }; 3711 struct entry4 { 3712 cookie4 cookie; 3713 filename4 name; 3714 fattr4 attrs; 3715 entry4 *nextentry; 3716 }; 3718 struct dirlist4 { 3719 entry4 *entries; 3720 bool eof; 3721 }; 3723 struct READDIR4resok { 3724 dirlist4 reply; 3725 }; 3727 union READDIR4res switch (nfsstat4 status) { 3728 case NFS4_OK: 3729 READDIR4resok resok; 3730 default: 3731 void; 3732 }; 3734 /* 3735 * READLINK: Read symbolic link 3736 */ 3737 struct READLINK4resok { 3738 linktext4 link; 3740 Strawman NFS version 4 August 1998 3742 }; 3744 union READLINK4res switch (nfsstat4 status) { 3745 case NFS4_OK: 3746 READLINK4resok resok; 3747 default: 3748 void; 3749 }; 3751 /* 3752 * REMOVE: Remove filesystem object 3753 */ 3754 struct REMOVE4args { 3755 filename4 target; 3756 }; 3758 union REMOVE4res switch (nfsstat4 status) { 3759 case NFS4_OK: 3760 void; 3761 default: 3762 void; 3763 }; 3765 /* 3766 * RENAME: Rename directory entry 3767 */ 3768 struct RENAME4args { 3769 filename4 oldname; 3770 nfs_fh4 newdir; 3771 filename4 newname; 3772 }; 3774 union RENAME4res switch (nfsstat4 status) { 3775 case NFS4_OK: 3776 void; 3777 default: 3778 void; 3779 }; 3781 /* 3782 * SETATTR: Set attributes 3783 */ 3784 struct SETATTR4args { 3785 fattr4 obj_attributes; 3786 }; 3788 union SETATTR4res switch (nfsstat4 status) { 3789 case NFS4_OK: 3791 Strawman NFS version 4 August 1998 3793 void; 3794 default: 3795 void; 3796 }; 3798 /* 3799 * VERIFY: Verify attributes same 3800 */ 3801 struct VERIFY4args { 3802 bitmap4 attr_request; 3803 fattr4 obj_attributes; 3804 }; 3806 union VERIFY4res switch (nfsstat4 status) { 3807 case NFS4_OK: 3808 void; 3809 default: 3810 void; 3811 }; 3813 /* 3814 * WRITE: Write to file 3815 */ 3816 enum stable_how4 { 3817 UNSTABLE = 0, 3818 DATA_SYNC = 1, 3819 FILE_SYNC = 2 3820 }; 3822 struct WRITE4args { 3823 offset4 offset; 3824 count4 count; 3825 stable_how4 stable; 3826 opaque data<>; 3827 }; 3829 struct WRITE4resok { 3830 count4 count; 3831 stable_how4 committed; 3832 writeverf4 verf; 3833 }; 3835 union WRITE4res switch (nfsstat4 status) { 3836 case NFS4_OK: 3837 WRITE4resok resok; 3838 default: 3839 void; 3840 }; 3842 Strawman NFS version 4 August 1998 3844 /* 3845 * SECINFO: Obtain Available Security Mechanisms 3846 */ 3847 struct SECINFO4args { 3848 filename4 name; 3849 }; 3851 struct rpc_flavor_info { 3852 secoid4 oid; 3853 qop4 qop; 3854 rpc_gss_svc_t service; 3855 }; 3857 struct secinfo4 { 3858 rpc_flavor4 flavor; 3859 rpc_flavor_info *flavor_info; 3860 secinfo4 *nextentry; 3861 }; 3863 struct SECINFO4resok { 3864 secinfo4 reply; 3865 }; 3867 union SECINFO4res switch (nfsstat4 status) { 3868 case NFS4_OK: 3869 SECINFO4resok resok; 3870 default: 3871 void; 3872 }; 3874 enum opcode { 3875 OP_NULL = 0, 3876 OP_ACCESS = 1, 3877 OP_COMMIT = 2, 3878 OP_CREATE = 3, 3879 OP_GETATTR = 4, 3880 OP_GETFH = 5, 3881 OP_LINK = 6, 3882 OP_LOCKR = 7, 3883 OP_LOCKW = 8, 3884 OP_LOCKT = 9, 3885 OP_LOCKX = 10, 3886 OP_LOCKU = 11, 3887 OP_LOOKUP = 12, 3888 OP_LOOKUPP = 13, 3889 OP_NVERIFY = 14, 3890 OP_RESTOREFH = 15, 3892 Strawman NFS version 4 August 1998 3894 OP_SAVEFH = 16, 3895 OP_PUTFH = 17, 3896 OP_PUTROOTFH = 18, 3897 OP_READ = 19, 3898 OP_READDIR = 20, 3899 OP_READLINK = 21, 3900 OP_REMOVE = 22, 3901 OP_RENAME = 23, 3902 OP_SETATTR = 24, 3903 OP_VERIFY = 25, 3904 OP_WRITE = 26, 3905 OP_SECINFO = 27 3906 }; 3908 union opunion switch (unsigned opcode) { 3909 case OP_NULL: void; 3910 case OP_ACCESS: ACCESS4args opaccess; 3911 case OP_COMMIT: COMMIT4args opcommit; 3912 case OP_CREATE: CREATE4args opcreate; 3913 case OP_GETATTR: GETATTR4args opgettattr; 3914 case OP_GETFH: void; 3915 case OP_LINK: LINK4args oplink; 3916 case OP_LOCKR: LOCKR4args oplockr; 3917 case OP_LOCKW: LOCKW4args oplockw; 3918 case OP_LOCKT: LOCKT4args oplockt; 3919 case OP_LOCKX: LOCKX4args oplockx; 3920 case OP_LOCKU: LOCKU4args oplocku; 3921 case OP_LOOKUP: LOOKUP4args oplookup; 3922 case OP_LOOKUPP: void; 3923 case OP_NVERIFY: NVERIFY4args opnverify; 3924 case OP_RESTOREFH: void; 3925 case OP_SAVEFH: void; 3926 case OP_PUTFH: PUTFH4args opputfh; 3927 case OP_PUTROOTFH: void; 3928 case OP_READ: READ4args opread; 3929 case OP_READDIR: READDIR4args opreaddir; 3930 case OP_READLINK: void; 3931 case OP_REMOVE: REMOVE4args opremove; 3932 case OP_RENAME: RENAME4args oprename; 3933 case OP_SETATTR: SETATTR4args opsetattr; 3934 case OP_VERIFY: VERIFY4args opverify; 3935 case OP_WRITE: WRITE4args opwrite; 3936 case OP_SECINFO: SECINFO4args opsecinfo; 3937 }; 3939 struct op { 3940 opunion ops; 3941 }; 3943 Strawman NFS version 4 August 1998 3945 union resultdata switch (unsigned resop){ 3946 case OP_NULL: void; 3947 case OP_ACESS: ACCESS4res op; 3948 case OP_COMMIT: COMMIT4res opcommit; 3949 case OP_CREATE: CREATE4res opcreate; 3950 case OP_GETATTR: GETATTR4res opgetattr; 3951 case OP_GETFH: GETFH4res opgetfh; 3952 case OP_LINK: LINK4res oplink; 3953 case OP_LOCKR: LOCKR4res oplockr; 3954 case OP_LOCKW: LOCKW4res oplockw; 3955 case OP_LOCKT: LOCKT4res oplockt; 3956 case OP_LOCKX: LOCKX4res oplockx; 3957 case OP_LOCKU: LOCKU4res oplocku; 3958 case OP_LOOKUP: LOOKUP4res oplookup; 3959 case OP_LOOKUPP: LOOKUPP4res oplookupp; 3960 case OP_NVERIFY: NVERIFY4res opnverify; 3961 case OP_RESTOREFH: RESTOREFH4res oprestorefh; 3962 case OP_SAVEFH: SAVEFH4res opsavefh; 3963 case OP_PUTFH: PUTFH4res opputfh; 3964 case OP_PUTROOTFH: PUTROOTFH4res opputrootfh; 3965 case OP_READ: READ4res opread; 3966 case OP_READDIR: READDIR4res opreaddir; 3967 case OP_READLINK: READLINK4res opreadlink; 3968 case OP_REMOVE: REMOVE4res opremove; 3969 case OP_RENAME: RENAME4res oprename; 3970 case OP_SETATTR: SETATTR4res opsetattr; 3971 case OP_VERIFY: VERIFY4res opverify; 3972 case OP_WRITE: WRITE4res opwrite; 3973 case OP_SECINFO: SECINFO4res opsecinfo; 3974 }; 3976 struct COMPOUND4args { 3977 utf8string tag; 3978 op oplist<>; 3979 }; 3981 struct COMPOUND4resok { 3982 utf8string tag; 3983 resultdata data<>; 3984 }; 3986 union COMPOUND4res switch (nfsstat4 status){ 3987 case NFS4_OK: 3988 COMPOUND4resok resok; 3989 default: 3990 void; 3991 }; 3993 Strawman NFS version 4 August 1998 3995 /* 3996 * Remote file service routines 3997 */ 3998 program NFS4_PROGRAM { 3999 version NFS_V4 { 4000 void 4001 NFSPROC4_NULL(void) = 0; 4003 COMPOUND4res 4004 NFSPROC4_COMPOUND(COMPOUND4args) = 1; 4006 } = 4; 4007 } = 100003; 4009 Strawman NFS version 4 August 1998 4011 12. Bibliography 4013 [Gray] 4014 C. Gray, D. Cheriton, "Leases: An Efficient Fault-Tolerant Mechanism 4015 for Distributed File Cache Consistency," Proceedings of the Twelfth 4016 Symposium on Operating Systems Principles, p. 202-210, December 1989. 4018 [Juszczak] 4019 Juszczak, Chet, "Improving the Performance and Correctness of an NFS 4020 Server," USENIX Conference Proceedings, USENIX Association, Berkeley, 4021 CA, June 1990, pages 53-63. Describes reply cache implementation 4022 that avoids work in the server by handling duplicate requests. More 4023 important, though listed as a side-effect, the reply cache aids in 4024 the avoidance of destructive non-idempotent operation re-application 4025 -- improving correctness. 4027 [Kazar] 4028 Kazar, Michael Leon, "Synchronization and Caching Issues in the 4029 Andrew File System," USENIX Conference Proceedings, USENIX 4030 Association, Berkeley, CA, Dallas Winter 1988, pages 27-36. A 4031 description of the cache consistency scheme in AFS. Contrasted with 4032 other distributed file systems. 4034 [Macklem] 4035 Macklem, Rick, "Lessons Learned Tuning the 4.3BSD Reno Implementation 4036 of the NFS Protocol," Winter USENIX Conference Proceedings, USENIX 4037 Association, Berkeley, CA, January 1991. Describes performance work 4038 in tuning the 4.3BSD Reno NFS implementation. Describes performance 4039 improvement (reduced CPU loading) through elimination of data copies. 4041 [Mogul] 4042 Mogul, Jeffrey C., "A Recovery Protocol for Spritely NFS," USENIX 4043 File System Workshop Proceedings, Ann Arbor, MI, USENIX Association, 4044 Berkeley, CA, May 1992. Second paper on Spritely NFS proposes a 4045 lease-based scheme for recovering state of consistency protocol. 4047 [Nowicki] 4048 Nowicki, Bill, "Transport Issues in the Network File System," ACM 4049 SIGCOMM newsletter Computer Communication Review, April 1989. A 4050 brief description of the basis for the dynamic retransmission work. 4052 Strawman NFS version 4 August 1998 4054 [Pawlowski] 4055 Pawlowski, Brian, Ron Hixon, Mark Stein, Joseph Tumminaro, "Network 4056 Computing in the UNIX and IBM Mainframe Environment," Uniforum `89 4057 Conf. Proc., (1989) Description of an NFS server implementation for 4058 IBM's MVS operating system. 4060 [RFC1094] 4061 Sun Microsystems, Inc., "NFS: Network File System Protocol 4062 Specification", RFC1094, March 1989. 4064 ftp://ftp.isi.edu/in-notes/rfc1094.txt 4066 [RFC1813] 4067 Callaghan, B., Pawlowski, B., Staubach, P., "NFS Version 3 Protocol 4068 Specification", RFC1813, Sun Microsystems, Inc., June 1995. 4070 ftp://ftp.isi.edu/in-notes/rfc1813.txt 4072 [RFC1831] 4073 Srinivasan, R., "RPC: Remote Procedure Call Protocol Specification 4074 Version 2", RFC1831, Sun Microsystems, Inc., August 1995. 4076 ftp://ftp.isi.edu/in-notes/rfc1831.txt 4078 [RFC1832] 4079 Srinivasan, R., "XDR: External Data Representation Standard", 4080 RFC1832, Sun Microsystems, Inc., August 1995. 4082 ftp://ftp.isi.edu/in-notes/rfc1832.txt 4084 [RFC1833] 4085 Srinivasan, R., "Binding Protocols for ONC RPC Version 2", RFC1833, 4086 Sun Microsystems, Inc., August 1995. 4088 ftp://ftp.isi.edu/in-notes/rfc1833.txt 4090 [RFC2078] 4091 Linn, J., "Generic Security Service Application Program Interface, 4092 Version 2", RFC2078, OpenVision Technologies, January 1997. 4094 ftp://ftp.isi.edu/in-notes/rfc2078.txt 4096 Strawman NFS version 4 August 1998 4098 [RFC2203] 4099 Eisler, M., Chiu, A., Ling, L., "RPCSEC_GSS Protocol Specification" 4100 RFC2203, Sun Microsystems, Inc., August 1995. 4102 ftp://ftp.isi.edu/in-notes/rfc2203.txt 4104 [Sandberg] 4105 Sandberg, R., D. Goldberg, S. Kleiman, D. Walsh, B. Lyon, "Design 4106 and Implementation of the Sun Network Filesystem," USENIX Conference 4107 Proceedings, USENIX Association, Berkeley, CA, Summer 1985. The 4108 basic paper describing the SunOS implementation of the NFS version 2 4109 protocol, and discusses the goals, protocol specification and trade- 4110 offs. 4112 [SPNEGO] 4113 Baize, E., Pinkas, D., "The Simple and Protected GSS-API Negotiation 4114 Mechanism", draft-ietf-cat-snego-09.txt, Bull, April 1998. 4116 ftp://ftp.isi.edu/internet-drafts/draft-ietf-cat-snego-09.txt 4118 [Srinivasan] 4119 Srinivasan, V., Jeffrey C. Mogul, "Spritely NFS: Implementation and 4120 Performance of Cache Consistency Protocols", WRL Research Report 4121 89/5, Digital Equipment Corporation Western Research Laboratory, 100 4122 Hamilton Ave., Palo Alto, CA, 94301, May 1989. This paper analyzes 4123 the effect of applying a Sprite-like consistency protocol applied to 4124 standard NFS. The issues of recovery in a stateful environment are 4125 covered in [Mogul]. 4127 [X/OpenNFS] 4128 X/Open Company, Ltd., X/Open CAE Specification: Protocols for X/Open 4129 Internetworking: XNFS, X/Open Company, Ltd., Apex Plaza, Forbury 4130 Road, Reading Berkshire, RG1 1AX, United Kingdom, 1991. This is an 4131 indispensable reference for NFS version 2 protocol and accompanying 4132 protocols, including the Lock Manager and the Portmapper. 4134 [X/OpenPCNFS] 4135 X/Open Company, Ltd., X/Open CAE Specification: Protocols for X/Open 4136 Internetworking: (PC)NFS, Developer's Specification, X/Open Company, 4137 Ltd., Apex Plaza, Forbury Road, Reading Berkshire, RG1 1AX, United 4138 Kingdom, 1991. This is an indispensable reference for NFS version 2 4139 protocol and accompanying protocols, including the Lock Manager and 4140 the Portmapper. 4142 Strawman NFS version 4 August 1998 4144 13. Author's Address 4146 Address comments related to this memorandum to: 4148 nfsv4-wg@sunroof.eng.sun.com 4150 Spencer Shepler 4151 Sun Microsystems, Inc. 4152 7808 Moonflower Drive 4153 Austin, Texas 78750 4155 Phone: 1-512-349-9376 4156 E-mail: shepler@eng.sun.com