idnits 2.17.1 draft-shepler-nfsv4-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. 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 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? == Mismatching filename: the document gives the document name as 'draft-ietf-nfsv4-00', but the file name used is 'draft-shepler-nfsv4-03' == 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 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.) ** The abstract seems to contain references ([RFC1094], [RFC1813]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 4484 has weird spacing: '...S4resok reso...' == Line 4503 has weird spacing: '...T4resok reso...' == Line 4553 has weird spacing: '...ckowner owne...' == Line 4574 has weird spacing: '...ckowner owner...' == Line 4593 has weird spacing: '...ient_id clie...' == (6 more instances...) -- 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 (February 1999) is 9195 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 5177 looks like a reference -- Missing reference section? 'RFC1813' on line 5189 looks like a reference -- Missing reference section? 'RFC1831' on line 5195 looks like a reference -- Missing reference section? 'RFC1832' on line 5201 looks like a reference -- Missing reference section? 'RFC2203' on line 5239 looks like a reference -- Missing reference section? 'RFC1833' on line 5207 looks like a reference -- Missing reference section? 'RFC2078' on line 5227 looks like a reference -- Missing reference section? 'RFC1964' on line 245 looks like a reference -- Missing reference section? 'RFC2054' on line 5215 looks like a reference -- Missing reference section? 'RFC2055' on line 5221 looks like a reference -- Missing reference section? 'XNFS' on line 5290 looks like a reference -- Missing reference section? '4' on line 1367 looks like a reference -- Missing reference section? 'RFC 2078' on line 3533 looks like a reference -- Missing reference section? 'RFC1345' on line 5183 looks like a reference -- Missing reference section? 'RFC2279' on line 5245 looks like a reference -- Missing reference section? 'RFC2152' on line 5233 looks like a reference -- Missing reference section? 'Unicode1' on line 5277 looks like a reference -- Missing reference section? 'Unicode2' on line 5284 looks like a reference -- Missing reference section? 'Gray' on line 5130 looks like a reference -- Missing reference section? 'Juszczak' on line 5135 looks like a reference -- Missing reference section? 'Kazar' on line 5144 looks like a reference -- Missing reference section? 'Macklem' on line 5151 looks like a reference -- Missing reference section? 'Mogul' on line 5275 looks like a reference -- Missing reference section? 'Nowicki' on line 5164 looks like a reference -- Missing reference section? 'Pawlowski' on line 5171 looks like a reference -- Missing reference section? 'Sandberg' on line 5251 looks like a reference -- Missing reference section? 'SPNEGO' on line 5262 looks like a reference -- Missing reference section? 'Srinivasan' on line 5268 looks like a reference Summary: 5 errors (**), 0 flaws (~~), 9 warnings (==), 31 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NFS Version 4 Working Group S. Shepler 3 INTERNET-DRAFT B. Callaghan 4 Document: draft-ietf-nfsv4-00.txt M. Eisler 5 D. Robinson 6 R. Thurlow 7 Sun Microsystems 8 February 1999 10 NFS version 4 12 Status of this Memo 14 This document is an Internet-Draft and is in full conformance with 15 all provisions of Section 10 of RFC2026. 17 Internet-Drafts are working documents of the Internet Engineering 18 Task Force (IETF), its areas, and its working groups. Note that 19 other groups may also distribute working documents as Internet- 20 Drafts. 22 Internet-Drafts are draft documents valid for a maximum of six months 23 and may be updated, replaced, or obsoleted by other documents at any 24 time. It is inappropriate to use Internet- Drafts as reference 25 material or to cite them other than as "work in progress." 27 The list of current Internet-Drafts can be accessed at 28 http://www.ietf.org/ietf/1id-abstracts.txt 30 The list of Internet-Draft Shadow Directories can be accessed at 31 http://www.ietf.org/shadow.html. 33 Abstract 35 NFS version 4 is a distributed file system protocol which owes 36 heritage to NFS versions 2 [RFC1094] and 3 [RFC1813]. Unlike earlier 37 versions, NFS version 4 supports traditional file access while 38 integrating support for file locking and the mount protocol. In 39 addition, support for strong security (and its negotiation), compound 40 operations, and internationlization have been added. Of course, 41 attention has been applied to making NFS version 4 operate well in an 42 Internet environment. 44 Draft Protocol Specification NFS version 4 February 1999 46 Copyright 48 Copyright (C) The Internet Society (1999). All Rights Reserved. 50 Key Words 52 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 53 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 54 document are to be interpreted as described in RFC 2119. 56 Draft Protocol Specification NFS version 4 February 1999 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 6 61 2. RPC and Security Flavor . . . . . . . . . . . . . . . . . . 7 62 2.1. Ports and Transports . . . . . . . . . . . . . . . . . . . 7 63 2.2. Security Flavors . . . . . . . . . . . . . . . . . . . . . 7 64 2.2.1. Security mechanisms for NFS version 4 . . . . . . . . . 7 65 2.2.1.1. Kerberos V5 as security triple . . . . . . . . . . . . 7 66 2.2.1.2. . . . . . . . . . . . . . . 8 67 2.3. Security Negotiation . . . . . . . . . . . . . . . . . . . 8 68 2.3.1. Security Error . . . . . . . . . . . . . . . . . . . . . 8 69 2.3.2. SECINFO . . . . . . . . . . . . . . . . . . . . . . . . 9 70 3. File handles . . . . . . . . . . . . . . . . . . . . . . . 10 71 3.1. Obtaining the first file handle . . . . . . . . . . . . 10 72 3.2. The persistent and volatile file handle . . . . . . . . 10 73 4. Basic Data Types . . . . . . . . . . . . . . . . . . . . . 12 74 5. File Attributes . . . . . . . . . . . . . . . . . . . . . 14 75 5.1. Mandatory attributes . . . . . . . . . . . . . . . . . . 15 76 5.2. Recommended attributes . . . . . . . . . . . . . . . . . 15 77 5.3. Extended attributes . . . . . . . . . . . . . . . . . . 16 78 5.4. Mandatory Attributes - Definitions . . . . . . . . . . . 16 79 5.5. Recommended Attributes - Definitions . . . . . . . . . . 18 80 6. NFS Server Namespace . . . . . . . . . . . . . . . . . . . 28 81 6.1. Server Exports . . . . . . . . . . . . . . . . . . . . . 28 82 6.2. Browsing Exports . . . . . . . . . . . . . . . . . . . . 28 83 6.3. Server Pseudo File-System . . . . . . . . . . . . . . . 29 84 6.4. Multiple Roots . . . . . . . . . . . . . . . . . . . . . 29 85 6.5. Filehandle Volatility . . . . . . . . . . . . . . . . . 29 86 6.6. Exported Root . . . . . . . . . . . . . . . . . . . . . 29 87 6.7. Mount Point Crossing . . . . . . . . . . . . . . . . . . 30 88 6.8. Summary . . . . . . . . . . . . . . . . . . . . . . . . 30 89 7. File Locking . . . . . . . . . . . . . . . . . . . . . . . 31 90 7.1. Definitions . . . . . . . . . . . . . . . . . . . . . . 31 91 7.2. Locking . . . . . . . . . . . . . . . . . . . . . . . . 32 92 7.2.1. Client ID . . . . . . . . . . . . . . . . . . . . . . 32 93 7.2.2. nfs_lockowner and stateid definition . . . . . . . . . 34 94 7.2.3. Use of the stateid . . . . . . . . . . . . . . . . . . 34 95 7.2.4. Sequencing of lock requests . . . . . . . . . . . . . 35 96 7.3. Blocking locks . . . . . . . . . . . . . . . . . . . . . 35 97 7.4. Lease renewal . . . . . . . . . . . . . . . . . . . . . 36 98 7.5. Crash recovery . . . . . . . . . . . . . . . . . . . . . 36 99 7.6. Server revocation of locks . . . . . . . . . . . . . . . 37 100 7.7. Share reservations . . . . . . . . . . . . . . . . . . . 38 101 7.8. OPEN/CLOSE procedures . . . . . . . . . . . . . . . . . 38 102 8. Defined Error Numbers . . . . . . . . . . . . . . . . . . 40 103 9. Compound Requests . . . . . . . . . . . . . . . . . . . . 44 104 10. NFS Version 4 Requests . . . . . . . . . . . . . . . . . 45 105 10.1. Evaluation of a Compound Request . . . . . . . . . . . 45 107 Draft Protocol Specification NFS version 4 February 1999 109 11. NFS Version 4 Procedures . . . . . . . . . . . . . . . . 46 110 11.1. Procedure 0: NULL - No operation . . . . . . . . . . . 47 111 11.2. Procedure 1: ACCESS - Check Access Permission . . . . . 48 112 11.3. Procedure 2: CLOSE - close file . . . . . . . . . . . . 51 113 11.4. Procedure 3: COMMIT - Commit cached data . . . . . . . 52 114 11.5. Procedure 4: CREATE - Create a non-regular file object 55 115 11.6. Procedure 5: GETATTR - Get attributes . . . . . . . . . 59 116 11.7. Procedure 6: GETFH - Get current filehandle . . . . . . 60 117 11.8. Procedure 7: LINK - Create link to an object . . . . . 61 118 11.9. Procedure 8: LOCK - Create lock . . . . . . . . . . . . 63 119 11.10. Procedure 9: LOCKT - test for lock . . . . . . . . . . 64 120 11.11. Procedure 10: LOCKU - Unlock file . . . . . . . . . . 65 121 11.12. Procedure 11: LOOKUP - Lookup filename . . . . . . . . 66 122 11.13. Procedure 12: LOOKUPP - Lookup parent directory . . . 68 123 11.14. Procedure 13: NVERIFY - Verify attributes different . 69 124 11.15. Procedure 14: OPEN - Open a regular file . . . . . . . 70 125 11.16. Procedure 15: PUTFH - Set current filehandle . . . . . 73 126 11.17. Procedure 16: PUTROOTFH - Set root filehandle . . . . 74 127 11.18. Procedure 17: READ - Read from file . . . . . . . . . 75 128 11.19. Procedure 18: READDIR - Read directory . . . . . . . . 78 129 11.20. Procedure 19: READLINK - Read symbolic link . . . . . 81 130 11.21. Procedure 20: REMOVE - Remove filesystem object . . . 83 131 11.22. Procedure 21: RENAME - Rename directory entry . . . . 85 132 11.23. Procedure 22: RENEW - renew a lease . . . . . . . . . 87 133 11.24. Procedure 23: RESTOREFH - Restore saved filehandle . . 88 134 11.25. Procedure 24: SAVEFH - Save current filehandle . . . . 89 135 11.26. Procedure 25: SECINFO - Obtain Available Security . . 90 136 11.27. Procedure 26: SETATTR - Set attributes . . . . . . . . 92 137 11.28. Procedure 27: SETCLIENTID - negotiated clientid . . . 94 138 11.29. Procedure 28: VERIFY - Verify attributes same . . . . 95 139 11.30. Procedure 29: WRITE - Write to file . . . . . . . . . 96 140 12. Locking notes . . . . . . . . . . . . . . . . . . . . . . 101 141 12.1. Short and long leases . . . . . . . . . . . . . . . . . 101 142 12.2. Clocks and leases . . . . . . . . . . . . . . . . . . . 101 143 12.3. Locks and lease times . . . . . . . . . . . . . . . . . 101 144 12.4. Locking of directories and other meta-files . . . . . . 102 145 12.5. Proxy servers and leases . . . . . . . . . . . . . . . 102 146 12.6. Locking and the new latency . . . . . . . . . . . . . . 102 147 13. Internationalization . . . . . . . . . . . . . . . . . . 103 148 13.1. Universal Versus Local Character Sets . . . . . . . . . 103 149 13.2. Overview of Universal Character Set Standards . . . . . 104 150 13.3. Difficulties with UCS-4, UCS-2, Unicode . . . . . . . . 105 151 13.4. UTF-8 and its solutions . . . . . . . . . . . . . . . . 106 152 14. Security Considerations . . . . . . . . . . . . . . . . . 107 153 15. NFS Version 4 RPC definition file . . . . . . . . . . . . 108 154 16. Bibliography . . . . . . . . . . . . . . . . . . . . . . 127 155 17. Authors and Contributors . . . . . . . . . . . . . . . . 131 156 17.1. Contributors . . . . . . . . . . . . . . . . . . . . . 131 158 Draft Protocol Specification NFS version 4 February 1999 160 17.2. Editor's Address . . . . . . . . . . . . . . . . . . . 131 161 17.3. Authors' Addresses . . . . . . . . . . . . . . . . . . 131 162 18. Full Copyright Statement . . . . . . . . . . . . . . . . 133 164 Draft Protocol Specification NFS version 4 February 1999 166 1. Introduction 168 NFS version 4 is a further revision of the NFS protocol defined 169 already by versions 2 [RFC1094] and 3 [RFC1813]. It retains the 170 essential characteristics of previous versions: stateless design for 171 easy recovery, independent of transport protocols, operating systems 172 and filesystems, simplicity, and good performance. The NFS version 4 173 revision has the following goals: 175 o Improved access and good performance on the Internet. 177 The protocol is designed to transit firewalls easily, perform 178 well where latency is high and bandwidth is low, and scale to 179 very large numbers of clients per server. 181 o Strong security with negotiation built into the protocol. 183 The protocol builds on the work of the ONCRPC working group in 184 supporting the RPCSEC_GSS protocol. Additionally NFS version 4 185 provides a mechanism to allow clients and servers to negotiate 186 security and require clients and servers to support a minimal 187 set of security schemes. 189 o Good cross-platform interoperability. 191 The protocol features a filesystem model that provides a useful, 192 common set of features that does not unduly favor one filesystem 193 or operating system over another. 195 o Designed for protocol extensions. 197 The protocol is designed to accept standard extensions that do 198 not compromise backward compatibility. 200 Draft Protocol Specification NFS version 4 February 1999 202 2. RPC and Security Flavor 204 The NFS version 4 protocol is a Remote Procedure Call (RPC) 205 application that uses RPC version 2 and the corresponding eXternal 206 Data Representation (XDR) as defined in [RFC1831] and [RFC1832]. The 207 RPCSEC_GSS security flavor as defined in [RFC2203] MUST be used as 208 the mechanism to deliver stronger security to NFS version 4. 210 2.1. Ports and Transports 212 Historically, NFS version 2 and version 3 servers have resided on 213 UDP/TCP port 2049. Port 2049 is a IANA registered port number for NFS 214 and therefore will continue to be used for NFS version 4. Using the 215 well known port for NFS services means the NFS client will not need 216 to use the RPC binding protocols as described in [RFC1833]; this will 217 allow NFS to transit firewalls. 219 The NFS server SHOULD offer its RPC service via TCP as the primary 220 transport. The server SHOULD also provide UDP for RPC service. The 221 NFS client SHOULD also have a preference for TCP usage but may supply 222 a mechanism to override TCP in favor of UDP as the RPC transport. 224 2.2. Security Flavors 226 Traditional RPC implementations have included AUTH_NONE, AUTH_SYS, 227 AUTH_DH, and AUTH_KRB4 as security flavors. With [RFC2203] an 228 additional security flavor of RPCSEC_GSS has been introduced which 229 uses the functionality of GSS-API [RFC2078]. This allows for the use 230 of varying security mechanisms by the RPC layer without the 231 additional implementation overhead of adding RPC security flavors. 232 For NFS version 4, the RPCSEC_GSS security flavor MUST be used to 233 enable the mandatory security mechanism. The flavors AUTH_NONE, 234 AUTH_SYS, and AUTH_DH MAY be implemented as well. 236 2.2.1. Security mechanisms for NFS version 4 238 The use of RPCSEC_GSS requires selection of: mechanism, quality of 239 protection, and service (authentication, integrity, privacy). The 240 remainder of this document will refer to these three parameters of 241 the RPCSEC_GSS security as the security triple. 243 2.2.1.1. Kerberos V5 as security triple 245 The Kerberos V5 GSS-API mechanism as described in [RFC1964] MUST be 246 implemented and provide the following security triples. 248 columns: 250 Draft Protocol Specification NFS version 4 February 1999 252 1 == number of pseudo flavor 253 2 == name of pseudo flavor 254 3 == mechanism's OID 255 4 == mechanism's algorithm(s) 256 5 == RPCSEC_GSS service 258 1 2 3 4 5 259 ----------------------------------------------------------------------- 260 390003 krb5 1.2.840.113554.1.2.2 DES MAC MD5 rpc_gss_svc_none 261 390004 krb5i 1.2.840.113554.1.2.2 DES MAC MD5 rpc_gss_svc_integrity 262 390005 krb5p 1.2.840.113554.1.2.2 DES MAC MD5 rpc_gss_svc_privacy 263 for integrity, 264 and 56 bit DES 265 for privacy. 267 This section will be expanded to include the pertinent 268 details from draft-ietf-nfsv4-nfssec-00.txt. 270 2.2.1.2. 272 Another GSS-API mechanism will need to be specified here 273 along with the corresponding security triple(s). 275 2.3. Security Negotiation 277 With the NFS version 4 server potentially offering multiple security 278 mechanisms, the client will need a way to determine or negotiate 279 which mechanism is to be used for its communication with the server. 280 The NFS server may have multiple points within its file system name 281 space that are available for use by NFS clients. In turn the NFS 282 server may be configured such that each of these entry points may 283 have different or multiple security mechanisms in use. 285 The security negotiation between client and server must be done with 286 a secure channel to eliminate the possibility of a third party 287 intercepting the negotiation sequence and forcing the client and 288 server to choose a lower level of security than required/desired. 290 2.3.1. Security Error 292 Based on the assumption that each NFS version 4 client and server 293 must support a minimum set of security (i.e. Kerberos-V5 under 294 RPCSEC_GSS, ), the NFS client will start its 295 communication with the server with one of the minimal security 297 Draft Protocol Specification NFS version 4 February 1999 299 triples. During communication with the server, the client may 300 receive an NFS error of NFS4ERR_WRONGSEC. This error allows the 301 server to notify the client that the security triple currently being 302 used is not appropriate for access to the server's file system 303 resources. The client is then responsible for determining what 304 security triples are available at the server and choose one which is 305 appropriate for the client. 307 2.3.2. SECINFO 309 The new procedure SECINFO (see SECINFO procedure definition) will 310 allow the client to determine, on a per filehandle basis, what 311 security triple is to be used for server access. In general, the 312 client will not have to use the SECINFO procedure except during 313 initial communication with the server or when the client crosses 314 policy boundaries at the server. It could happen that the server's 315 policies change during the client's interaction therefore forcing the 316 client to negotiate a new security triple. 318 Draft Protocol Specification NFS version 4 February 1999 320 3. File handles 322 The file handle in the NFS protocol is an opaque identifier for a 323 file system object. The server is responsible for translating the 324 file handle to its internal representation of the file system object. 325 The file handle is used to uniquely identify a file system object at 326 the NFS server. The client should be able to depend on the fact that 327 a file handle will not be reused once a file system object has been 328 destroyed. If the file handle is reused, the time elapsed before 329 reuse SHOULD be very significant. Note that each NFS procedure is 330 defined in terms of its file handle(s) except for the NULL procedure. 332 3.1. Obtaining the first file handle 334 If each of the meaningful operations of the NFS protocol require a 335 file handle, the client must have a mechanism to obtain the first 336 file handle. With NFS version 2 [RFC1094] and NFS version 3 337 [RFC1813], there exists an ancillary, protocol to obtain the first 338 file handle. The MOUNT protocol, RPC program number 100005, provides 339 the mechanism of translating a string based file system path name to 340 a file handle which can then be used by the NFS protocols. 342 The MOUNT protocol as currently implemented has deficiencies in the 343 area of security and use via firewalls. This is one reason that the 344 use of the public file handle was introduced [RFC2054] [RFC2055]. 345 The public file handle is a special case file handle that is used in 346 combination with a path name to avoid using the MOUNT protocol for 347 obtaining the first file handle. With the introduction and use of 348 the public file handle in the previous versions of NFS, it has been 349 shown that the MOUNT protocol is unnecessary for viable interaction 350 between the client and server with the use of file handles. 352 3.2. The persistent and volatile file handle 354 For the first time in NFS version 4, the file handle constructed by 355 the server can be volatile. In the previous versions of NFS, the 356 server was responsible for ensuring the persistence of the file 357 handle. This meant that as long as a file system object remained in 358 existence at the server the file handle for that object had to be the 359 same each time the client asked for it. This persistent quality 360 eased the implementation at the client in the event of server restart 361 or failure and recovery. For some servers, fulfilling the persistent 362 requirement has been straight forward; for others it has been 363 difficult and affected at best performance and at worst correctness. 365 The existence of the volatile file handle requires the client to 366 implement a method of recovering from the expiration of a file 367 handle. Most commonly the client will need to store the component 369 Draft Protocol Specification NFS version 4 February 1999 371 names associated with the file system object in question. With these 372 names, the client will be able to recover by finding a file handle in 373 the name space that is still available or by starting at the root of 374 the server's file system name space. 376 The use of a volatile file handle provides these advantages: 378 o Eases the server implementation requirements. 380 o Server can provide extended services more easily with the use of 381 volatile file handles (HSM software, file system reorganization) 383 o Allows for server file systems that have difficulty in mapping a 384 stable file handle to a file object. In this case, a server 385 implementation would be able to build a mapping dynamically 386 between a volatile file handle and the file system object. 388 In some cases a file handle is stale (no longer valid, perhaps 389 because the file was removed from the server), or it is expired (the 390 underlying file is valid, but since the file handle is volatile, it 391 may have expired, requiring the client to get a new file handle). 392 Thus the server needs to be able to return NFS4ERR_STALE in the 393 former case, and NFS4ERR_EXPIRED in the latter case. This can be done 394 by careful construction of the volatile file handle. One 395 implementation that has been suggested is the following. A volatile 396 file handle, while opaque to the client could contain: 398 volatile bit = 1 | server boot time | slot | generation number 400 slot is an index in the server volatile file handle table. generation 401 number is the generation number for the table entry/slot. If the 402 server boot time is less than the current server boot time, return 403 NFS4ERR_EXPIRED. If slot is out of range, return NFS4ERR_EXPIRED. If 404 the generation number does not match, return NFS4ERR_EXPIRED. 406 When the server reboots, the table is gone (it is volatile). 408 If volatile bit is 0, then it is a persistent file handle with a 409 different structure following it. 411 Draft Protocol Specification NFS version 4 February 1999 413 4. Basic Data Types 415 Arguments and results from operations will be described in terms of 416 basic XDR types defined in [RFC1832]. The following data types will 417 be defined in terms of basic XDR types: 419 filehandle: opaque <128> 421 An NFS version 4 filehandle. A filehandle with zero length is 422 recognized as a "public" filehandle. 424 utf8string: opaque <> 426 A counted array of octets that contains a UTF-8 string. 428 Note: Section 11, Internationalization, covers the rational of 429 using UTF-8. 431 bitmap: uint32 <> 433 A counted array of 32 bit integers used to contain bit values. 434 The position of the integer in the array that contains bit n can 435 be computed from the expression (n / 32) and its bit within that 436 integer is (n mod 32). 438 0 1 439 +-----------+-----------+-----------+-- 440 | count | 31 .. 0 | 63 .. 32 | 441 +-----------+-----------+-----------+-- 443 createverf: opaque<8> 445 Verify used for exclusive create semantics 447 nfstime4 448 struct nfstime4 { 449 int64_t seconds; 450 uint32_t nseconds; 451 } 453 The nfstime4 structure gives the number of seconds and 454 nanoseconds since midnight or 0 hour January 1, 1970 Coordinated 455 Universal Time (UTC). Values greater than zero for the seconds 456 field denote dates after the 0 hour January 1, 1970. Values 457 less than zero for the seconds field denote dates before the 0 458 hour January 1, 1970. In both cases, the nseconds field is to 459 be added to the seconds field for the final time representation. 460 For example, if the time to be represented is one-half second 462 Draft Protocol Specification NFS version 4 February 1999 464 before 0 hour January 1, 1970, the seconds field would have a 465 value of negative one (-1) and the nseconds fields would have a 466 value of one-half second (500000000). Values greater than 467 999,999,999 for nseconds are considered invalid. 469 This data type is used to pass time and date information. A 470 server converts to and from local time when processing time 471 values, preserving as much accuracy as possible. If the 472 precision of timestamps stored for a file system object is less 473 than defined, loss of precision can occur. An adjunct time 474 maintenance protocol is recommended to reduce client and server 475 time skew. 477 specdata4 478 struct specdata4 { 479 uint32_t specdata1; 480 uint32_t specdata2; 481 } 483 This data type represents additional information for the device 484 file types NFCHR and NFBLK. 486 Draft Protocol Specification NFS version 4 February 1999 488 5. File Attributes 490 To meet the NFS Version 4 requirements of extensibility and increased 491 interoperability with non-Unix platforms, attributes must be handled 492 in a more flexible manner. The NFS Version 3 fattr3 structure 493 contained a fixed list of attributes that not all clients and servers 494 are able to support or care about, which cannot be extended as new 495 needs crop up, and which provides no way to indicate non-support. 496 With NFS Version 4, the client will be able to ask what attributes 497 the server supports, and will be able to request only those 498 attributes in which it is interested. 500 To this end, attributes will be divided into three groups: mandatory, 501 recommended and extended. Both mandatory and recommended attributes 502 are supported in the NFS V4 protocol by a specific and well-defined 503 encoding, and are identified by number. They are requested by 504 setting a bit in the bit vector sent in the GETATTR request; the 505 server response includes a bit vector to list what attributes were 506 returned in response. New mandatory or recommended attributes may be 507 added to the NFS protocol between revisions by publishing a 508 standards-track RFC which allocates a new attribute number value and 509 defines the encoding for the attribute. 511 Extended attributes are accessed by the new OPENATTR operation, which 512 accesses a hidden directory of attributes associated with a 513 filesystem object. OPENATTR takes a filehandle for the object and 514 returns the filehandle for the attribute hierarchy, which is a 515 directory object accessible by LOOKUP or READDIR, and which contains 516 files whose names and are the names of the extended attributes and 517 whose data bytes are the value of the attribute. For example: 519 LOOKUP "foo" ; look up file 520 GETATTR attrbits 521 OPENATTR ; access foo's extended attributes 522 LOOKUP "x11icon" ; look up specific attribute 523 READ 0,4096 ; read stream of bytes 525 Extended attributes are intended primarily for data needed by 526 applications rather than by an NFS client implementation per se; NFS 527 implementors are strongly encouraged to define their new attributes 528 as recommended attributes by bringing them to the working group. 530 The set of attributes which are classified as mandatory is 531 deliberately small, since servers must do whatever it takes to 532 support them. The recommended attributes may be unsupported, though 533 a server should support as many as it can. Attributes are deemed 535 Draft Protocol Specification NFS version 4 February 1999 537 mandatory if the data is both needed by a large number of clients and 538 is not otherwise reasonably computable by the client when support is 539 not provided on the server. 541 5.1. Mandatory attributes 543 These MUST be supported by every NFS Version 4 client and server in 544 order to ensure a minimum level of interoperability. The server must 545 store and return these attributes, and the client must be able to 546 function with an attribute set limited to these attributes, though 547 some operations may be impaired or limited in some ways in this case. 548 A client may ask for any of these attributes to be returned by 549 setting a bit in the GETATTR request, and the server must return 550 their value. 552 5.2. Recommended attributes 554 These attributes are understood well enough to warrant support in the 555 NFS Version 4 protocol, though they may not be supported on all 556 clients and servers. A client may ask for any of these attributes to 557 be returned by setting a bit in the GETATTR request, but must be able 558 to deal with not receiving them. A client may ask for the set of 559 attributes the server supports and should not request attributes the 560 server does not support. A server should be tolerant of requests for 561 unsupported attributes, and simply not return them, rather than 562 considering the request an error. It is expected that servers will 563 support all attributes they comfortably can, and only fail to support 564 attributes which are difficult to support in their operating 565 environments. A server should provide attributes whenever they don't 566 have to "tell lies" to the client - for example, a file modification 567 time should be either an accurate time or should not be supported by 568 the server. This will not always be comfortable to clients, but in 569 general it seems that the client has a better ability to fake data or 570 do without. 572 Most attributes from NFS V3's FSINFO, FSSTAT and PATHCONF procedures 573 have been added as recommended attributes, so that filesystem info 574 may be collected via the filehandle of any object the filesystem. 575 This renders those procedures unnecessary in NFS V4. If a server 576 supports any per-filesystem attributes, it must support the fsid 577 attribute so that the client may always determine when filesystems 578 are crossed so that it can work correctly with these attributes. 580 Draft Protocol Specification NFS version 4 February 1999 582 5.3. Extended attributes 584 These attributes are not supported by direct encoding in the NFS 585 Version 4 protocol, but are accessed by string names rather than 586 numbers, and correspond to an uninterpreted stream of bytes which are 587 stored with the filesystem object. The namespace for these 588 attributes may be accessed by using the OPENATTR operation to get a 589 filehandle for a virtual "attribute directory" and using READDIR and 590 LOOKUP operations on this filehandle. Extended attributes may then 591 be examined or changed by normal READ and WRITE and CREATE operations 592 on the filehandles returned from READDIR and LOOKUP. Attributes may 593 have attributes, for example, a security label may have access 594 control information in its own right. 596 It is recommended that servers support arbitrary extended attributes. 597 A client should not depend on the ability to store any extended 598 attributes in the server's filesystem. If a server does support 599 extended attributes, a client which is also able to handle them 600 should be able to copy a file's data and meta-data with complete 601 transparency from one location to another; this would imply that 602 there should be no attribute names which will be considered illegal 603 by the server. 605 Names of attributes will not be controlled by a standards body, 606 however vendors and application writers are encouraged to register 607 attribute names and the interpretation and semantics of the stream of 608 bytes via informational RFC so that vendors may interoperate where 609 common interests exist. 611 The following is a list of mandatory and recommended attributes. 613 5.4. Mandatory Attributes - Definitions 615 Name: supp_attr 617 Data Type: nfs_attrvec4 619 Access: Read 621 Description: the bit vector which would retrieve all mandatory and 622 recommended attributes which may be requested for 623 this object 625 Justification: the client must ask this question to request correct 626 attributes 628 Draft Protocol Specification NFS version 4 February 1999 630 Name: object_type 632 Data Type: nfs_type4 634 Access: Read 636 Description: the type of the object (file/directory/symlink) 638 Justification: the client cannot handle object correctly without 639 type 641 Name: object_size 643 Data Type: uint64 645 Access: Read Write 647 Description: the size of the object in bytes 649 Justification: could be very expensive to derive, likely to be 650 available 652 Name: change 654 Data Type: uint64 656 Description: A value created by the server that the client can use 657 to determine if a file data, directory contents or 658 attributes have been modified. The server can just 659 return the file mtime in this field though if a more 660 precise value exists then it can be substituted, for 661 instance, a checksum or sequence number. 663 Justification: necessary for any useful caching, likely to be 664 available 666 Name: persistent_fh 668 Data Type: boolean 670 Access: Read 672 Description: is the filehandle for this object persistent? 674 Draft Protocol Specification NFS version 4 February 1999 676 Justification: Server should know if the file handles being provided 677 are persistent or not. If the server is not able to 678 make this determination, then it can choose volatile 679 or non-persistent. 681 Name: extended 683 Data Type: boolean 685 Access: Read 687 Description: whether or not this object has extended attributes 689 Justification: 691 Name: link_support 693 Data Type: boolean 695 Access: Read 697 Description: whether or not this object's filesystem supports hard 698 links 700 Justification: Server can easily determine if links are supported 702 Name: symlink_support 704 Data Type: boolean 706 Access: Read 708 Description: whether or not this object's filesystem supports 709 symbolic links 711 Justification: Server can easily determine if links are supported 713 5.5. Recommended Attributes - Definitions 715 Name: owner 717 Data Type: utf8<> 719 Draft Protocol Specification NFS version 4 February 1999 721 Access: Read Write 723 Description: the string name of the owner of this object; note 724 that the concept of a numeric uid has been dropped 726 Name: group_owner 728 Data Type: utf8<> 730 Access: Read Write 732 Description: the string name of the group of the owner of this 733 object; note that the concept of a numeric gid has 734 been dropped 736 Name: file_id 738 Data Type: fileid4 740 Access: Read 742 Description: a number uniquely identifying the file within the 743 filesystem 745 Name: file_name 747 Data Type: utf8<> 749 Access: Read 751 Description: the name of this object (primarily for readdir 752 requests) 754 Name: filehandle 756 Data Type: nfs_fh4 758 Access: Read 760 Description: the filehandle of this object (primarily for readdir 761 requests) 763 Name: ACL 765 Draft Protocol Specification NFS version 4 February 1999 767 Data Type: nfsacl4 769 Access: Read Write 771 Description: the access control list for the object [The nature 772 and format of ACLs is still to be determined.] 774 Name: mode 776 Data Type: uint32 778 Access: Read Write 780 Description: Unix-style permission bits for this object 781 (deprecated in favor of ACLs) 783 Name: object_links 785 Data Type: uint32 787 Access: Read 789 Description: number of links to this object 791 Name: space_used 793 Data Type: uint64 795 Access: Read 797 Description: number of filesystem bytes allocated to this object 799 Name: fsid.major 801 Data Type: uint64 803 Access: Read 805 Description: unique filesystem identifier for the filesystem 806 holding this object 808 Name: fsid.minor 810 Draft Protocol Specification NFS version 4 February 1999 812 Data Type: uint64 814 Access: Read 816 Description: unique filesystem identifier within the fsid.major 817 filesystem identifier for the filesystem holding this 818 object 820 Name: quota_used 822 Data Type: uint64 824 Access: Read 826 Description: number of bytes of disk space occupied by the owner 827 of this object on this filesystem 829 Name: quota_soft 831 Data Type: uint64 833 Access: Read 835 Description: number of bytes of disk space at which the client may 836 choose to warn the user about limited space 838 Name: quota_hard 840 Data Type: uint64 842 Access: Read 844 Description: number of bytes of disk space beyond which the server 845 will decline to allocate new space 847 Name: rawdev 849 Data Type: specdata4 851 Access: Read 853 Description: raw device identifier 855 Draft Protocol Specification NFS version 4 February 1999 857 Name: access_time 859 Data Type: nfstime4 861 Access: Read Write 863 Description: the time of last access to the object 865 Name: create_time 867 Data Type: nfstime4 869 Access: Read Write 871 Description: the time of creation of the object. This attribute 872 does not have any relation to the traditional Unix 873 file attribute 'ctime' or 'change time'. 875 Name: meta-data_time 877 Data Type: nfstime4 879 Access: Read Write 881 Description: the time of last meta-data modification of the 882 object. 884 Name: mod_time 886 Data Type: nfstime4 888 Access: Read Write 890 Description: the time since the epoch of last modification to the 891 object 893 Name: backup_time 895 Data Type: nfstime4 897 Access: Read Write 899 Description: the time of last backup of the object 901 Draft Protocol Specification NFS version 4 February 1999 903 Name: mime_type 905 Data Type: utf8<> 907 Access: Read Write 909 Description: MIME body type/subtype of this object 911 Name: version 913 Data Type: utf8<> 915 Access: Read Write 917 Description: version number of this document 919 Name: hidden 921 Data Type: boolean 923 Access: Read Write 925 Description: whether or not this file is considered hidden 927 Name: archive 929 Data Type: boolean 931 Access: Read Write 933 Description: whether or not this file has been archived since the 934 time of last modification (deprecated in favor of 935 backup_time) 937 Name: system 939 Data Type: boolean 941 Access: Read Write 943 Description: whether or not this file is a system file 945 Name: homogeneous 947 Draft Protocol Specification NFS version 4 February 1999 949 Data Type: boolean 951 Access: Read 953 Description: whether or not this object's filesystem is 954 homogeneous, i.e. whether pathconf is the same for 955 all filesystem objects 957 Name: cansettime 959 Data Type: boolean 961 Access: Read 963 Description: whether or not this object's filesystem can fill in 964 the times on a SETATTR request without an explicit 965 time 967 Name: no_trunc 969 Data Type: boolean 971 Access: Read 973 Description: if a name longer than name_max is used, will an error 974 be returned or will the name be truncated? 976 Name: chown_restricted 978 Data Type: boolean 980 Access: Read 982 Description: will a request to change ownership be honored? 984 Name: case_insensitive 986 Data Type: boolean 988 Access: Read 990 Description: are filename comparisons on this filesystem case 991 insensitive? 993 Draft Protocol Specification NFS version 4 February 1999 995 Name: case_preserving 997 Data Type: boolean 999 Access: Read 1001 Description: is filename case on this filesystem preserved? 1003 Name: name_max 1005 Data Type: uint32 1007 Access: Read 1009 Description: maximum filename size supported for this object 1011 Name: link_max 1013 Data Type: uint32 1015 Access: Read 1017 Description: maximum number of links for this object 1019 Name: read_max 1021 Data Type: uint64 1023 Access: Read 1025 Description: maximum read size supported for this object 1027 Name: write_max 1029 Data Type: uint64 1031 Access: Read 1033 Description: maximum write size supported for this object. This 1034 attribute SHOULD be supported if the file is 1035 writable. Lack of this attribute can lead to the 1036 client either wasting bandwidth or not receiving the 1037 best performance. 1039 Draft Protocol Specification NFS version 4 February 1999 1041 Name: maxfilesize 1043 Data Type: uint64 1045 Access: Read 1047 Description: maximum supported file size for the filesystem of 1048 this object 1050 Name: time_delta 1052 Data Type: nfstime4 1054 Access: Read 1056 Description: smallest useful server time granularity 1058 Name: total_space 1060 Data Type: uint64 1062 Access: Read 1064 Description: total disk space in bytes on the filesystem 1065 containing this object 1067 Name: free_space 1069 Data Type: uint64 1071 Access: Read 1073 Description: free disk space in bytes on the filesystem containing 1074 this object - this should be the smallest relevant 1075 limit 1077 Name: avail_space 1079 Data Type: uint64 1081 Access: Read 1083 Description: disk space in bytes available to this user on the 1084 filesystem containing this object - this should be 1086 Draft Protocol Specification NFS version 4 February 1999 1088 the smallest relevant limit 1090 Name: total_files 1092 Data Type: uint64 1094 Access: Read 1096 Description: total file slots on the filesystem containing this 1097 object 1099 Name: free_files 1101 Data Type: uint64 1103 Access: Read 1105 Description: free file slots on the filesystem containing this 1106 object - this should be the smallest relevant limit 1108 Name: avail_files 1110 Data Type: uint64 1112 Access: Read 1114 Description: file slots available to this user on the filesystem 1115 containing this object - this should be the smallest 1116 relevant limit 1118 Name: volatility 1120 Data Type: nfstime4 1122 Access: Read 1124 Description: approximate time until next expected change on this 1125 filesystem, as a measure of volatility 1127 Draft Protocol Specification NFS version 4 February 1999 1129 6. NFS Server Namespace 1131 6.1. Server Exports 1133 On a UNIX server the name-space describes all the files reachable by 1134 pathnames under the root directory "/". On a Windows NT server the 1135 name-space constitutes all the files on disks named by mapped disk 1136 letters. NFS server administrators rarely make the entire server's 1137 file-system name-space available to NFS clients. Typically, pieces 1138 of the name-space are made available via an "export" feature. The 1139 root filehandle for each export is obtained through the MOUNT 1140 protocol; the client sends a string that identifies the export of 1141 name-space and the server returns the root filehandle for it. The 1142 MOUNT protocol supports an EXPORTS procedure that will enumerate the 1143 server's exports. 1145 6.2. Browsing Exports 1147 The NFS version 4 protocol provides a root filehandle that clients 1148 can use to obtain filehandles for these exports via a multi-component 1149 LOOKUP. A common user experience is to use a graphical user 1150 interface (perhaps a file "Open" dialog window) to find a file via 1151 progressive browsing through a directory tree. The client must be 1152 able to move from one export to another export via single-component, 1153 progressive LOOKUP operations. 1155 This style of browsing is not well supported by NFS version 2 and 3 1156 protocols. The client expects all LOOKUP operations to remain within 1157 a single server file-system, i.e. the device attribute will not 1158 change. This prevents a client from taking name-space paths that 1159 span exports. 1161 An automounter on the client can obtain a snapshot of the server's 1162 name-space using the EXPORTS procedure of the MOUNT protocol. If it 1163 understands the server's pathname syntax, it can create an image of 1164 the server's name-space on the client. The parts of the name-space 1165 that are not exported by the server are filled in with a "pseudo 1166 file-system" that allows the user to browse from one mounted file- 1167 system to another. There is a drawback to this representation of the 1168 server's name-space on the client: it is static. If the server 1169 administrator adds a new export the client will be unaware of it. 1171 Draft Protocol Specification NFS version 4 February 1999 1173 6.3. Server Pseudo File-System 1175 NFS version 4 servers avoid this name-space inconsistency by 1176 presenting all the exports within the framework of a single server 1177 name-space. An NFS version 4 client uses LOOKUP and READDIR 1178 operations to browse seamlessly from one export to another. Portions 1179 of the server name-space that are not exported are bridged via a 1180 "pseudo file-system" that provides a view only of exported 1181 directories. The pseudo file-system has a unique fsid and behaves 1182 like a normal, read-only file-system. 1184 6.4. Multiple Roots 1186 DOS, Windows 95, 98 and NT are sometimes described as having 1187 "multiple roots". File-Systems are commonly represented as disk 1188 letters. MacOS represents file-systems as top-level names. NFS 1189 version 4 servers for these platforms can construct a pseudo file- 1190 system above these root names so that disk letters or volume names 1191 are simply directory names in the pseudo-root. 1193 6.5. Filehandle Volatility 1195 The nature of the server's pseudo file-system is that it is a logical 1196 representation of file-system(s) available from the server. 1197 Therefore, the pseudo file-system is most likely constructed 1198 dynamically when the NFS version 4 is first instantiated. It is 1199 expected the pseudo file-system may not have an on-disk counterpart 1200 from which persistent filehandles could be constructed. Even though 1201 it is preferable that the server provide persistent filehandles for 1202 the pseudo file-system, the NFS client should expect that pseudo 1203 file-system file-handles are volatile. This can be confirmed by 1204 checking the associated "persistent_fh" attribute for those 1205 filehandles in question. If the filehandles are volatile, the NFS 1206 client must be prepared to recover a filehandle value (i.e. with a v4 1207 multi-component LOOKUP) when receiving an error of NFS4ERR_FHEXPIRED. 1209 6.6. Exported Root 1211 If the server's root file-system is exported, it might be easy to 1212 conclude that a pseudo-file-system is not needed. This would be 1213 wrong. Assume the following file-systems on a server: 1215 / disk1 (exported) 1216 /a disk2 (not exported) 1218 Draft Protocol Specification NFS version 4 February 1999 1220 /a/b disk3 (exported) 1222 Because disk2 is not exported, disk3 cannot be reached with simple 1223 LOOKUPs. The server must bridge the gap with a pseudo-file-system. 1225 6.7. Mount Point Crossing 1227 The server file-system environment may constructed in such a way that 1228 one file-system contains a directory which is 'covered' or mounted 1229 upon by a second file-system. For example: 1231 /a/b (file system 1) 1232 /a/b/c/d (file system 2) 1234 The pseudo file-system for this server may be constructed to look 1235 like: 1237 / (place holder/not exported) 1238 /a/b (file system 1) 1239 /a/b/c/d (file system 2) 1241 It is the server's responsibility to present the pseudo file-system 1242 that is complete to the client. If the client sends a lookup request 1243 for the path "/a/b/c/d", the server's response is the filehandle of 1244 the file system "/a/b/c/d". In previous versions of NFS, the server 1245 would respond with the directory "/a/b/d/d" within the file-system 1246 "/a/b". 1248 The NFS client will be able to determine if it crosses a server mount 1249 point by a change in the value of the "fsid" attribute. 1251 6.8. Summary 1253 NFS version 4 provides LOOKUP and READDIR operations for browsing of 1254 NFS file-systems. These operations are also used to browse server 1255 exports. A v4 server supports export browsing by including exported 1256 directories in a pseudo-file-system. A browsing client can cross 1257 seamlessly between a pseudo-file-system and a real, exported file- 1258 system. Clients must support volatile filehandles and recognize 1259 mount point crossing of server file-systems. 1261 Draft Protocol Specification NFS version 4 February 1999 1263 7. File Locking 1265 Integrating locking into NFS necessarily causes it to be state-full, 1266 with the invasive nature of "share" file locks it becomes 1267 substantially more dependent on state than the traditional 1268 combination of NFS and NLM [XNFS]. There are three components to 1269 making this state manageable: 1271 o Clear division between client and server 1273 o Ability to reliably detect inconsistency in state between client 1274 and server 1276 o Simple and robust recovery mechanisms 1278 In this model, the server owns the state information. The client 1279 communicates its view of this state to the server as needed. The 1280 client is also able to detect inconsistent state before modifying a 1281 file. 1283 To support Windows "share" locks, it is necessary to atomically open 1284 or create files. Having a separate share/unshare operation will not 1285 allow correct implementation of the Windows OpenFile API. In order 1286 to correctly implement share semantics, the existing mechanisms used 1287 when a file is opened or created (LOOKUP, CREATE, ACCESS) need to be 1288 replaced. NFS V4 will have an OPEN procedure that subsumes the 1289 functionality of LOOKUP, CREATE, and ACCESS. However, because many 1290 operations require a file handle, the traditional LOOKUP is preserved 1291 to map a file name to file handle without establishing state on the 1292 server. Policy of granting access or modifying files is managed by 1293 the server based on the client's state. It is believed that these 1294 mechanisms can implement policy ranging from advisory only locking to 1295 full mandatory locking. While ACCESS is just a subset of OPEN, the 1296 ACCESS procedure is maintained as a lighter weight mechanism. 1298 7.1. Definitions 1300 Lock The term "lock" will be used to refer to both record 1301 (byte-range) locks as well as file (share) locks unless 1302 specifically stated otherwise. 1304 Client Throughout this proposal the term "client" is used to 1305 indicate the entity that maintains a set of locks on behalf 1306 of one or more applications. The client is responsible for 1307 crash recovery of those locks it manages. Multiple clients 1308 may share the same transport and multiple clients may exist 1310 Draft Protocol Specification NFS version 4 February 1999 1312 on the same network node. 1314 Clientid A 64-bit quantity returned by a server that uniquely 1315 corresponds to a client supplied Verifier and ID. 1317 Lease An interval of time defined by the server for which the 1318 client is irrevokeably granted a lock. At the end of a 1319 lease period the lock may be revoked if the lease has not 1320 been extended. The lock must be revoked if a conflicting 1321 lock has been granted after the lease interval. All leases 1322 granted by a server have the same fixed interval. 1324 Stateid A 64-bit quantity returned by a server that uniquely 1325 defines the locking state granted by the server for a 1326 specific lock owner for a specific file. A stateid 1327 composed of all bits 0 or all bits 1 have special meaning 1328 and are reserved. 1330 Verifier A 32-bit quantity generated by the client that the server 1331 can use to determine if the client has restarted and lost 1332 all previous lock state. 1334 7.2. Locking 1336 It is assumed that manipulating a lock is rare when compared to I/O 1337 operations. It is also assumed that crashes and network partitions 1338 are relatively rare. Therefore it is important that I/O operations 1339 have a light weight mechanism to indicate if they possess a held 1340 lock. A lock request contains the heavy weight information required 1341 to establish a lock and uniquely define the lock owner. 1343 The following sections describe the transition from the heavy weight 1344 information to the eventual stateid used for most client and server 1345 locking and lease interactions. 1347 7.2.1. Client ID 1349 For each LOCK request, the client must identify itself to the server. 1350 This is done in such a way as to allow for correct lock 1351 identification and crash recovery. Client identification is 1352 accomplished with two values. 1354 o A verifier that is used to detect client reboots. 1356 o A variable length opaque array to uniquely define a client. 1358 For an operating system this may be a fully qualified host 1360 Draft Protocol Specification NFS version 4 February 1999 1362 name or IP address, and for a user level NFS client it may 1363 additionally contain a process id or other unique sequence. 1365 The data structure for the Client ID would then appear as: 1366 struct nfs_client_id { 1367 opaque verifier[4]; 1368 opaque id<>; 1369 }: 1371 It is possible through the mis-configuration of a client or the 1372 existence of a rogue client that two clients end up using the same 1373 nfs_client_id. This situation is avoided by 'negotiating' the 1374 nfs_client_id between client and server with the use of the 1375 SETCLIENTID. The following describes the two scenarios of 1376 negotiation. 1378 1 Client has never connected to the server 1380 In this case the client generates an nfs_client_id and 1381 unless another client has the same nfs_client_id.id field, 1382 the server accepts the request. The server also records the 1383 principal (or principal to uid mapping) from the credential 1384 in the RPC request that contains the nfs_client_id 1385 negotiation request. 1387 Two clients might still use the same nfs_client_id.id due 1388 to perhaps configuration error (say a High Availability 1389 configuration where the nfs_client_id.id is derived from 1390 the ethernet controller address and both systems have the 1391 same address). In this case, nfs4err can be a switched 1392 union that returns in addition to NFS4ERR_CLID_IN_USE, the 1393 network address (the rpcbind netid and universal address) 1394 of the client that is using the id. 1396 2 Client is re-connecting to the server after a client reboot 1398 In this case, the client still generates an nfs_client_id 1399 but the nfs_client_id.id field will be the same as the 1400 nfs_client_id.id generated prior to reboot. If the server 1401 finds that the principal/uid is equal to the previously 1402 "registered" nfs_client_id.id, then locks associated with 1403 the old nfs_client_id are immediately released. If the 1404 principal/uid is not equal, then this ia rogue client and 1405 the request is returned in error. For more discussion of 1406 crash recovery semantics, see the section on "Crash 1407 Recovery" 1409 Draft Protocol Specification NFS version 4 February 1999 1411 In both cases, upon success, NFS4_OK is returned. To help reduce the 1412 amount of data transferred on OPEN and LOCK, the server will also 1413 return a unique 64-bit clientid value that is a short hand reference 1414 to the nfs_client_id values presented by the client. From this point 1415 forward, the client can use the clientid to refer to itself. 1417 7.2.2. nfs_lockowner and stateid definition 1419 When requesting a lock, the client must present to the server the 1420 clientid and an identifier for the owner of the requested lock. 1421 These two fields are referred to as the nfs_lockowner and the 1422 definition of those fields are: 1424 o A clientid returned by the server as part of the clients use of 1425 the SETCLIENTID procedure 1427 o A variable length opaque array used to uniquely define the owner 1428 of a lock managed by the client. 1430 This may be a thread id, process id, or other unique value. 1432 When the server grants the lock it responds with a unique 64-bit 1433 stateid. The stateid is used as a short hand reference to the 1434 nfs_lockowner, since the server will be maintaining the 1435 correspondence between them. 1437 7.2.3. Use of the stateid 1439 All I/O requests contain a stateid. If the nfs_lockowner performs 1440 I/O on a range of bytes within a locked range, the stateid returned 1441 by the server must be used to indicate the appropriate lock (record 1442 or share) is held. If no state is established by the client, either 1443 record lock or share lock, a stateid of all bits 0 is used. If no 1444 conflicting locks are held on the file, the server may grant the I/O 1445 request. If a conflict with an explicit lock occurs, the request is 1446 failed (NFS4ERR_LOCKED). This allows "mandatory locking" to be 1447 implemented. 1449 A stateid of all bits 1 allows read requests to bypass locking checks 1450 at the server. However, write requests with stateid with bits all 1 1451 does not bypass file locking requirements. 1453 An explicit lock may not be granted while an I/O operation with 1454 conflicting implicit locking is being performed. 1456 Draft Protocol Specification NFS version 4 February 1999 1458 The byte range of a lock is indivisible. A range may be locked, 1459 unlocked, or changed between read and write but may not have 1460 subranges unlocked or changed between read and write. This is the 1461 semantics provided by Win32 but only a subset of the semantics 1462 provided by Unix. It is expected that Unix clients can more easily 1463 simulate modifying subranges than Win32 servers adding this feature. 1465 7.2.4. Sequencing of lock requests 1467 Locking is different than most NFS operations as it requires "at- 1468 most-one" semantics that are not provided by ONC RPC. In the face of 1469 retransmission or reordering, lock or unlock requests must have a 1470 well defined and consistent behavior. To accomplish this each lock 1471 request contains a sequence number that is a monotonically increasing 1472 integer. Different nfs_lockowners have different sequences. The 1473 server maintains the last sequence number (L) received and the 1474 response that was returned. If a request with a previous sequence 1475 number (r < L) is received it is silently ignored as its response 1476 must have been received before the last request (L) was sent. If a 1477 duplicate of last request (r == L) is received, the stored response 1478 is returned. If a request beyond the next sequence (r == L + 2) is 1479 received it is silently ignored. Sequences are reinitialized 1480 whenever the client verifier changes. 1482 7.3. Blocking locks 1484 Some clients require the support of blocking locks. The current 1485 proposal lacks a call-back mechanism, similar to NLM, to notify a 1486 client when the lock has been granted. Clients have no choice but to 1487 continually poll for the lock, which presents a fairness problem. 1488 Two new lock types are added, READW and WRITEW used to indicate to 1489 the server that the client is requesting a blocking lock. The server 1490 should maintain an ordered list of pending blocking locks. When the 1491 conflicting lock is released, the server may wait the lease period 1492 for the first client to re-request the lock. After the lease period 1493 expires the next waiting client request is allowed the lock. Clients 1494 are required to poll at an interval sufficiently small that it is 1495 likely to acquire the lock in a timely manner. The server is not 1496 required to maintain a list of pending blocked locks as it is used to 1497 increase fairness and not correct operation. Because of the 1498 unordered nature of crash recovery, storing of lock state to stable 1499 storage would be required to guarantee ordered granting of blocking 1500 locks. 1502 Draft Protocol Specification NFS version 4 February 1999 1504 7.4. Lease renewal 1506 The purpose of a lease is to allow a server to remove stale locks 1507 that are held by a client that has crashed or is otherwise 1508 unreachable. It is not a mechanism for cache consistency and lease 1509 renewals may not be denied if the lease interval has not expired. 1510 Any I/O request that has been made with a valid stateid is a positive 1511 indication that the client is still alive and locks are being 1512 maintained. This becomes an implicit renewal of the lease. In the 1513 case no I/O has been performed within the lease interval, a lease can 1514 be renewed by having the client issue a zero length READ. Because 1515 the nfs_lockowner contains a unique client value, any stateid for a 1516 client will renew all leases for locks held with the same client 1517 field. This will allow very low overhead lease renewal that scales 1518 extremely well. In the typical case, no extra RPC calls are needed 1519 and in the worst case one RPC is required every lease period 1520 regardless of the number of locks held by the client. 1522 7.5. Crash recovery 1524 The important requirement in crash recovery is that both the client 1525 and the server know when the other has failed. Additionally it is 1526 required that a client sees a consistent view of data across server 1527 reboots. I/O operations that may have been queued within the client 1528 or network buffers, cannot complete until after the client has 1529 successfully recovered the lock protecting the I/O operation. 1531 If a client fails, the server only needs to wait the lease period to 1532 allow conflicting locks. If the client reinitializes within the 1533 lease period, it may be forced to wait the remainder of the period 1534 before resuming service. To minimize this delay, lock requests 1535 contain a verifier field in the lock_owner, if the server receives a 1536 verifier field that does not match the existing verifier, the server 1537 knows that the client has lost all lock state and locks held for that 1538 client that do not match the current verifier may be released. In a 1539 secure environment, a change in the verifier must only cause the 1540 locks held by the authenticated requester to be released in order to 1541 prevent a rogue user from freeing otherwise valid locks. The 1542 verifier must have the same uniqueness properties of the COMMIT 1543 verifier. 1545 If the server fails and loses locking state, the server must wait the 1546 lease period before granting any new locks or allowing any I/O. An 1547 I/O request during the grace period with an invalid stateid will fail 1548 with NFS4ERR_GRACE, the client will reissue the lock request with 1549 reclaim set to TRUE, and upon receiving a successful reply, the I/O 1550 may be reissued with the new stateid. Any time a client receives an 1552 Draft Protocol Specification NFS version 4 February 1999 1554 NFS4ERR_GRACE error it should start recovering all outstanding locks. 1555 A lock request during the grace period without reclaim set will also 1556 result in a NFS4ERR_GRACE, triggering the client recovery processing. 1557 A lock request outside the grace period with reclaim set will succeed 1558 only if the server can guarantee that no conflicting lock or I/O 1559 request has been granted since reboot. 1561 In the case of a network partition longer than the lease period, the 1562 server will have not received an implicit lease renewal and may free 1563 all locks held for the client, thus invalidating any stateid held by 1564 the client. Subsequent reconnection will cause I/O with invalid 1565 stateid to fail with NFS4ERR_EXPIRED, the client will suitably notify 1566 the application holding the lock. After the lease period has expired 1567 the server may optionally continue to hold the locks for the client. 1568 In this case, if a conflicting lock or I/O request is received, the 1569 lock must be freed to allow the client to detect possible corruption. 1570 When there is a network partition and the lease expires, the server 1571 must record on stable storage the client information relating to 1572 those leases. This is to prevent the case where another client 1573 obtains the conflicting lock, frees the lock, and the server reboots. 1574 After the server recovers the original client may recover the network 1575 partition and attempt to reclaim the lock. Without any state to 1576 indicate that a conflicting may have occurred, the client could get 1577 in an inconsistent state. Storing just the client information is the 1578 minimal state necessary to detect this condition, but could lead to 1579 losing locks unnecessarily. However this is considered to be a very 1580 rare event, and a sophisticated server could store more state 1581 completely eliminate any unnecessary locks being lost. 1583 7.6. Server revocation of locks 1585 The server can revoke the locks held by a client at any time, when 1586 the client detects revocation it must ensure its state matches that 1587 of the server. If locks are revoked due to a server reboot, the 1588 client will receive a NFS4ERR_GRACE and normal crash recovery 1589 described above will be performed. 1591 The server may revoke a lock within the lease period, this is 1592 considered a rare event likely to be initiated only by a human (as 1593 part of an administration task). The client may assume that only the 1594 file that caused the NFS4ERR_EXPIRED to be returned has lost the 1595 lock_owner's locks and notifies the holder appropriately. The client 1596 can not assume the lease period has been renewed. 1598 The client not being able to renew the lease period is a relatively 1599 rare and unusual state. Both sides will detect this state and can 1600 recover without data corruption. The client must mark all locks held 1602 Draft Protocol Specification NFS version 4 February 1999 1604 as "invalidated" and then must issue an I/O request, either a pending 1605 I/O or zero length read to revalidate the lock. If the response is 1606 success the lock is upgraded to valid, otherwise it was revoked by 1607 the server and the owner is notified. 1609 7.7. Share reservations 1611 A share reservation is a mechanism to control access to a file. It 1612 is a separate and independent mechanism from record locking. When a 1613 client that shares opens a file, it issues an OPEN request to the 1614 server specifying the type of access required (READ, WRITE, or BOTH) 1615 and the type of access to deny others (deny NONE, READ, WRITE, or 1616 BOTH). If the OPEN fails the client will fail the applications open 1617 request. 1619 Pseudo-code definition of the semantics: 1621 if ((request.access & file_state.deny)) || 1622 (request.deny & file_state.access)) 1623 return (NFS4ERR_DENIED) 1625 Old DOS applications specify shares in compatibility mode. Microsoft 1626 has indicated in the Win32 specification that it will be deprecated 1627 in the future and recommends that deny NONE be used. This 1628 specification does not support compatibility mode. 1630 7.8. OPEN/CLOSE procedures 1632 To provide correct semantics for share semantics, a client MUST use 1633 the OPEN procedure to obtain the initial file handle and indicate the 1634 desired access and what if any access to deny. Even if the client 1635 intends to use a stateid of all 0's or all 1's, it must still obtain 1636 the filehandle for the regular file with the OPEN procedure. For 1637 clients that do not have a deny mode built into their open API, deny 1638 equal to NONE should be used. 1640 The OPEN procedure with the CREATE flag, also subsumes the CREATE 1641 procedure for regular files as used in previous versions of NFS, 1642 allowing a create with a share to be done atomicly. 1644 Will expand on create semantics here. 1646 The CLOSE procedure removes all share locks held by the lock_owner on 1648 Draft Protocol Specification NFS version 4 February 1999 1650 that file. If record locks are held they should be explicitly 1651 unlocked. Some servers may not support the CLOSE of a file that 1652 still has record locks held; if so, CLOSE will fail and return an 1653 error. 1655 The LOOKUP procedure is preserved and will return a file handle 1656 without establishing any lock state on the server. Without a valid 1657 stateid, the server will assume the client has the least access. For 1658 example, a file opened with deny READ/WRITE cannot be accessed using 1659 a file handle obtained through LOOKUP. 1661 Draft Protocol Specification NFS version 4 February 1999 1663 8. Defined Error Numbers 1665 NFS error numbers are assigned to failed operations within a compound 1666 request. A compound request contains a number of NFS operations that 1667 have their results encoded in sequence in a compound reply. The 1668 results of successful operations will consist of an NFS4_OK status 1669 followed by the encoded results of the operation. If an NFS 1670 operation fails, an error status will be entered in the reply and the 1671 compound request will be terminated. 1673 A description of each defined error follows: 1675 NFS4_OK Indicates the operation completed successfully. 1677 NFS4ERR_PERM Not owner. The operation was not allowed because 1678 the caller is either not a privileged user (root) 1679 or not the owner of the target of the operation. 1681 NFS4ERR_NOENT No such file or directory. The file or directory 1682 name specified does not exist. 1684 NFS4ERR_IO I/O error. A hard error (for example, a disk 1685 error) occurred while processing the requested 1686 operation. 1688 NFS4ERR_NXIO I/O error. No such device or address. 1690 NFS4ERR_ACCES Permission denied. The caller does not have the 1691 correct permission to perform the requested 1692 operation. Contrast this with NFS4ERR_PERM, which 1693 restricts itself to owner or privileged user 1694 permission failures. 1696 NFS4ERR_DENIED An attempt to lock a file is denied. Since this 1697 may be a temporary condition, the client is 1698 encouraged to retry the lock request (with 1699 exponential backoff of timeout) until the lock is 1700 accepted. 1702 NFS4ERR_EXIST File exists. The file specified already exists. 1704 Draft Protocol Specification NFS version 4 February 1999 1706 NFS4ERR_XDEV Attempt to do a cross-device hard link. 1708 NFS4ERR_NODEV No such device. 1710 NFS4ERR_NOTDIR Not a directory. The caller specified a non- 1711 directory in a directory operation. 1713 NFS4ERR_ISDIR Is a directory. The caller specified a directory 1714 in a non-directory operation. 1716 NFS4ERR_INVAL Invalid argument or unsupported argument for an 1717 operation. Two examples are attempting a READLINK 1718 on an object other than a symbolic link or 1719 attempting to SETATTR a time field on a server 1720 that does not support this operation. 1722 NFS4ERR_FBIG File too large. The operation would have caused a 1723 file to grow beyond the server's limit. 1725 NFS4ERR_NOSPC No space left on device. The operation would have 1726 caused the server's file system to exceed its 1727 limit. 1729 NFS4ERR_ROFS Read-only file system. A modifying operation was 1730 attempted on a read-only file system. 1732 NFS4ERR_MLINK Too many hard links. 1734 NFS4ERR_NAMETOOLONG The filename in an operation was too long. 1736 NFS4ERR_NOTEMPTY An attempt was made to remove a directory that 1737 was not empty. 1739 NFS4ERR_DQUOT Resource (quota) hard limit exceeded. The user's 1740 resource limit on the server has been exceeded. 1742 Draft Protocol Specification NFS version 4 February 1999 1744 NFS4ERR_LOCKED A read or write operation was attempted on a 1745 locked file. 1747 NFS4ERR_STALE Invalid file handle. The file handle given in the 1748 arguments was invalid. The file referred to by 1749 that file handle no longer exists or access to it 1750 has been revoked. 1752 NFS4ERR_BADHANDLE Illegal NFS file handle. The file handle failed 1753 internal consistency checks. 1755 NFS4ERR_NOT_SYNC Update synchronization mismatch was detected 1756 during a SETATTR operation. 1758 NFS4ERR_BAD_COOKIE READDIR cookie is stale. 1760 NFS4ERR_NOTSUPP Operation is not supported. 1762 NFS4ERR_TOOSMALL Buffer or request is too small. 1764 NFS4ERR_SAME Returned if an NVERIFY operation shows that no 1765 attributes have changed. 1767 NFS4ERR_SERVERFAULT An error occurred on the server which does not 1768 map to any of the legal NFS version 4 protocol 1769 error values. The client should translate this 1770 into an appropriate error. UNIX clients may 1771 choose to translate this to EIO. 1773 NFS4ERR_BADTYPE An attempt was made to create an object of a type 1774 not supported by the server. 1776 NFS4ERR_JUKEBOX The server initiated the request, but was not 1777 able to complete it in a timely fashion. The 1778 client should wait and then try the request with 1779 a new RPC transaction ID. For example, this 1780 error should be returned from a server that 1781 supports hierarchical storage and receives a 1783 Draft Protocol Specification NFS version 4 February 1999 1785 request to process a file that has been migrated. 1786 In this case, the server should start the 1787 immigration process and respond to client with 1788 this error. 1790 NFS4ERR_FHEXPIRED The file handle provided is volatile and has 1791 expired at the server. The client should attempt 1792 to recover the new file handle by traversing the 1793 server's file system name space. The file handle 1794 may have expired because the server has 1795 restarted, the file system object has been 1796 removed, or the file handle has been flushed from 1797 the server's internal mappings. 1799 NOTE: This error definition will need to be crisp and match 1800 the section describing the volatile file handles. 1802 NFS4ERR_WRONGSEC THe security mechanism being used by the client 1803 for the procedure does not match the server's 1804 security policy. The client should change the 1805 security mechanism being used and retry the 1806 operation. 1808 Draft Protocol Specification NFS version 4 February 1999 1810 9. Compound Requests 1812 NFS version 4 requires a client to combine multiple NFS operations 1813 into a single request. Compound requests provide: 1815 o Good performance on high latency networks 1817 If a client can combine multiple, dependent operations into a 1818 single request then it can avoid the cumulative latency in many 1819 request/response round-trips across the network. This is 1820 particularly important on the Internet or through geosynchronous 1821 satellite connections. 1823 o Protocol simplification 1825 Clients can build NFS requests of arbitrary complexity from more 1826 primitive operations. These requests can be tailored to the 1827 unique needs of each client. 1829 A compound request looks like this: 1831 +-----------+-----------+-----------+-- 1832 | op + args | op + args | op + args | 1833 +-----------+-----------+-----------+-- 1835 and the reply looks like this: 1837 +----------------+----------------+----------------+-- 1838 | code + results | code + results | code + results | 1839 +----------------+----------------+----------------+-- 1841 Where "code" is an indication of the success or failure of the 1842 operation including the opcode itself. 1844 Draft Protocol Specification NFS version 4 February 1999 1846 10. NFS Version 4 Requests 1848 Nearly all NFS version 4 operations are defined as compound 1849 operations - not as RPC procedures. There is a single RPC procedure 1850 for all compound requests. 1852 10.1. Evaluation of a Compound Request 1854 The server evaluates the operations in sequence. Each operation 1855 consists of a 32 bit operation code, followed by a sequence of 1856 arguments of length determined by the type of operation. The results 1857 of each operation are encoded in sequence into a reply buffer. The 1858 results of each operation are preceded by the opcode and a status 1859 code (normally zero). If an operation fails a non-zero status code 1860 will be encoded, evaluation of the compound request will halt, and 1861 the reply will be returned. 1863 The client is responsible for recovering from any partially completed 1864 compound request. 1866 Each operation assumes a "current" filehandle that is available as 1867 part of the execution context of the compound request. Operations 1868 may set, change, or return this filehandle. 1870 Draft Protocol Specification NFS version 4 February 1999 1872 11. NFS Version 4 Procedures 1873 Draft Protocol Specification NFS version 4 February 1999 1875 11.1. Procedure 0: NULL - No operation 1877 SYNOPSIS 1879 (cfh) -> (cfh) 1881 ARGS 1883 (none) 1885 RESULTS 1887 (none) 1889 DESCRIPTION 1891 The server does no work other than to return a NFS_OK result in 1892 the reply. 1894 ERRORS 1896 (none) 1898 Draft Protocol Specification NFS version 4 February 1999 1900 11.2. Procedure 1: ACCESS - Check Access Permission 1902 SYNOPSIS 1904 (cfh), permbits -> permbits 1906 ARGS 1908 permbits: uint32 1910 RESULTS 1912 permbits: uint32 1914 DESCRIPTION 1916 ACCESS determines the access rights that a user, as identified by 1917 the credentials in the request, has with respect to a file system 1918 object. The client encodes the set of permissions that are to be 1919 checked in a bit mask. The server checks the permissions encoded 1920 in the bit mask. A status of NFS4_OK is returned along with a bit 1921 mask encoded with the permissions that the client is allowed. 1923 The results of this procedure are necessarily advisory in nature. 1924 That is, a return status of NFS4_OK and the appropriate bit set in 1925 the bit mask does not imply that such access will be allowed to 1926 the file system object in the future, as access rights can be 1927 revoked by the server at any time. 1929 The following access permissions may be requested: 1931 ACCESS_READ: bit 0 Read data from file or read 1932 a directory. 1933 ACCESS_LOOKUP: bit 1 Look up a name in a 1934 directory (no meaning for 1935 non-directory objects). 1936 ACCESS_MODIFY: bit 2 Rewrite existing file data or modify 1937 existing directory entries. 1938 ACCESS_EXTEND: bit 3 Write new data or add 1939 directory entries. 1940 ACCESS_DELETE: bit 4 Delete an existing 1941 directory entry. 1942 ACCESS_EXECUTE: bit 5 Execute file (no meaning 1943 for a directory). 1945 Draft Protocol Specification NFS version 4 February 1999 1947 The server must return an error if the any access permission 1948 cannot be determined. 1950 IMPLEMENTATION 1952 In general, it is not sufficient for the client to attempt to 1953 deduce access permissions by inspecting the uid, gid, and mode 1954 fields in the file attributes, since the server may perform uid or 1955 gid mapping or enforce additional access control restrictions. It 1956 is also possible that the NFS version 4 protocol server may not be 1957 in the same ID space as the NFS version 4 protocol client. In 1958 these cases (and perhaps others), the NFS version 4 protocol 1959 client can not reliably perform an access check with only current 1960 file attributes. 1962 In the NFS version 2 protocol, the only reliable way to determine 1963 whether an operation was allowed was to try it and see if it 1964 succeeded or failed. Using the ACCESS procedure in the NFS version 1965 4 protocol, the client can ask the server to indicate whether or 1966 not one or more classes of operations are permitted. The ACCESS 1967 operation is provided to allow clients to check before doing a 1968 series of operations. This is useful in operating systems (such as 1969 UNIX) where permission checking is done only when a directory is 1970 opened. This procedure is also invoked by NFS client access 1971 procedure (called possibly through access(2)). The intent is to 1972 make the behavior of opening a remote file more consistent with 1973 the behavior of opening a local file. 1975 For NFS version 4, the use of the ACCESS procedure when opening a 1976 regular file is deprecated in favor of using OPEN. 1978 The information returned by the server in response to an ACCESS 1979 call is not permanent. It was correct at the exact time that the 1980 server performed the checks, but not necessarily afterwards. The 1981 server can revoke access permission at any time. 1983 The NFS version 4 protocol client should use the effective 1984 credentials of the user to build the authentication information in 1985 the ACCESS request used to determine access rights. It is the 1986 effective user and group credentials that are used in subsequent 1987 read and write operations. 1989 Many implementations do not directly support the ACCESS_DELETE 1990 permission. Operating systems like UNIX will ignore the 1991 ACCESS_DELETE bit if set on an access request on a non-directory 1992 object. In these systems, delete permission on a file is 1993 determined by the access permissions on the directory in which the 1994 file resides, instead of being determined by the permissions of 1996 Draft Protocol Specification NFS version 4 February 1999 1998 the file itself. Thus, the bit mask returned for such a request 1999 will have the ACCESS_DELETE bit set to 0, indicating that the 2000 client does not have this permission. 2002 ERRORS 2004 NFS4ERR_IO 2006 NFS4ERR_SERVERFAULT 2008 SEE 2010 GETATTR. 2012 Draft Protocol Specification NFS version 4 February 1999 2014 11.3. Procedure 2: CLOSE - close file 2016 SYNOPSIS 2018 (cfh), stateid -> stateid 2020 ARGS 2022 stateid: uint64 2024 RESULTS 2026 stateid: uint64 2028 DESCRIPTION 2029 The CLOSE procedure notifies the server that all share locks 2030 corresponding to the client supplied stateid should be released. 2032 IMPLEMENTATION 2033 Share locks for the matching stateid will be released on 2034 successful completion of the CLOSE procedure. 2036 ERRORS 2037 To be determined 2039 SEE 2041 OPEN 2043 Draft Protocol Specification NFS version 4 February 1999 2045 11.4. Procedure 3: COMMIT - Commit cached data 2047 SYNOPSIS 2049 (cfh), offset, count -> verifier 2051 Procedure COMMIT forces or flushes data to stable storage that was 2052 previously written with a WRITE operation with the stable field 2053 set to UNSTABLE. 2055 ARGS 2057 offset: uint64 2059 The position within the file at which the flush is to begin. An 2060 offset of 0 means to flush data starting at the beginning of the 2061 file. 2063 count: uint32 2065 The number of bytes of data to flush. If count is 0, a flush from 2066 offset to the end of file is done. 2068 RESULTS 2070 verifier: uint32 2072 This is a cookie that the client can use to determine whether the 2073 server has rebooted between a call to WRITE and a subsequent call 2074 to COMMIT. This cookie must be consistent during a single boot 2075 session and must be unique between instances of the NFS version 4 2076 protocol server where uncommitted data may be lost. 2078 IMPLEMENTATION 2080 Procedure COMMIT is similar in operation and semantics to the 2081 POSIX fsync(2) system call that synchronizes a file's state with 2082 the disk, that is it flushes the file's data and metadata to disk. 2083 COMMIT performs the same operation for a client, flushing any 2084 unsynchronized data and metadata on the server to the server's 2085 disk for the specified file. Like fsync(2), it may be that there 2086 is some modified data or no modified data to synchronize. The data 2087 may have been synchronized by the server's normal periodic buffer 2088 synchronization activity. COMMIT will always return NFS4_OK, 2089 unless there has been an unexpected error. 2091 COMMIT differs from fsync(2) in that it is possible for the client 2093 Draft Protocol Specification NFS version 4 February 1999 2095 to flush a range of the file (most likely triggered by a buffer- 2096 reclamation scheme on the client before file has been completely 2097 written). 2099 The server implementation of COMMIT is reasonably simple. If the 2100 server receives a full file COMMIT request, that is starting at 2101 offset 0 and count 0, it should do the equivalent of fsync()'ing 2102 the file. Otherwise, it should arrange to have the cached data in 2103 the range specified by offset and count to be flushed to stable 2104 storage. In both cases, any metadata associated with the file 2105 must be flushed to stable storage before returning. It is not an 2106 error for there to be nothing to flush on the server. This means 2107 that the data and metadata that needed to be flushed have already 2108 been flushed or lost during the last server failure. 2110 The client implementation of COMMIT is a little more complex. 2111 There are two reasons for wanting to commit a client buffer to 2112 stable storage. The first is that the client wants to reuse a 2113 buffer. In this case, the offset and count of the buffer are sent 2114 to the server in the COMMIT request. The server then flushes any 2115 cached data based on the offset and count, and flushes any 2116 metadata associated with the file. It then returns the status of 2117 the flush and the verf verifier. The other reason for the client 2118 to generate a COMMIT is for a full file flush, such as may be done 2119 at close. In this case, the client would gather all of the buffers 2120 for this file that contain uncommitted data, do the COMMIT 2121 operation with an offset of 0 and count of 0, and then free all of 2122 those buffers. Any other dirty buffers would be sent to the 2123 server in the normal fashion. 2125 This implementation will require some modifications to the buffer 2126 cache on the client. After a buffer is written with stable 2127 UNSTABLE, it must be considered as dirty by the client system 2128 until it is either flushed via a COMMIT operation or written via a 2129 WRITE operation with stable set to FILE_SYNC or DATA_SYNC. This is 2130 done to prevent the buffer from being freed and reused before the 2131 data can be flushed to stable storage on the server. 2133 When a response comes back from either a WRITE or a COMMIT 2134 operation that contains an unexpected verf, the client will need 2135 to retransmit all of the buffers containing uncommitted cached 2136 data to the server. How this is to be done is up to the 2137 implementor. If there is only one buffer of interest, then it 2138 should probably be sent back over in a WRITE request with the 2139 appropriate stable flag. If there more than one, it might be 2140 worthwhile retransmitting all of the buffers in WRITE requests 2141 with stable set to UNSTABLE and then retransmitting the COMMIT 2142 operation to flush all of the data on the server to stable 2144 Draft Protocol Specification NFS version 4 February 1999 2146 storage. The timing of these retransmissions is left to the 2147 implementor. 2149 The above description applies to page-cache-based systems as well 2150 as buffer-cache-based systems. In those systems, the virtual 2151 memory system will need to be modified instead of the buffer 2152 cache. 2154 ERRORS 2156 NFS4ERR_IO NFS4ERR_LOCKED NFS4ERR_SERVERFAULT 2158 SEE 2160 WRITE. 2162 Draft Protocol Specification NFS version 4 February 1999 2164 11.5. Procedure 4: CREATE - Create a non-regular file object 2166 SYNOPSIS 2168 (cfh), name, type, how -> (cfh) 2170 ARGS 2172 name: utf8string 2174 objtype: filetype 2176 how: union 2178 UNCHECKED: 2179 GUARDED: 2181 attrbits: bitmap 2182 attrvals 2184 EXCLUSIVE: 2186 verifier: createverf 2188 RESULTS 2190 (cfh): filehandle 2192 DESCRIPTION 2194 Procedure CREATE creates an non-regular file object in a directory 2195 with a given name. The OPEN procedure MUST be used to create a 2196 regular file. 2198 The objtype determines the type of object to be created: 2199 directory, symlink, etc. The how union may have a value of 2200 UNCHECKED, GUARDED, and EXCLUSIVE. UNCHECKED means that the object 2201 should be created without checking for the existence of a 2202 duplicate object in the same directory. In this case, attrbits and 2203 attrvals describe the initial attributes for the file object. 2204 GUARDED specifies that the server should check for the presence of 2205 a duplicate object before performing the create and should fail 2206 the request with NFS4ERR_EXIST if a duplicate object exists. If 2207 the object does not exist, the request is performed as described 2208 for UNCHECKED. EXCLUSIVE specifies that the server is to follow 2209 exclusive creation semantics, using the verifier to ensure 2210 exclusive creation of the target. No attributes may be provided in 2212 Draft Protocol Specification NFS version 4 February 1999 2214 this case, since the server may use the target object meta-data to 2215 store the verifier. 2217 The current filehandle is replaced by that of the new object. 2219 IMPLEMENTATION 2220 The CREATE procedure carries support for EXCLUSIVE create forward 2221 from NFS version 3. As in NFS version 3, this mechanism provides 2222 reliable exclusive creation. Exclusive create is invoked when the 2223 how parameter is EXCLUSIVE. In this case, the client provides a 2224 verifier that can reasonably be expected to be unique. A 2225 combination of a client identifier, perhaps the client network 2226 address, and a unique number generated by the client, perhaps the 2227 RPC transaction identifier, may be appropriate. 2229 If the object does not exist, the server creates the object and 2230 stores the verifier in stable storage. For file systems that do 2231 not provide a mechanism for the storage of arbitrary file 2232 attributes, the server may use one or more elements of the object 2233 meta-data to store the verifier. The verifier must be stored in 2234 stable storage to prevent erroneous failure on retransmission of 2235 the request. It is assumed that an exclusive create is being 2236 performed because exclusive semantics are critical to the 2237 application. Because of the expected usage, exclusive CREATE does 2238 not rely solely on the normally volatile duplicate request cache 2239 for storage of the verifier. The duplicate request cache in 2240 volatile storage does not survive a crash and may actually flush 2241 on a long network partition, opening failure windows. In the UNIX 2242 local file system environment, the expected storage location for 2243 the verifier on creation is the meta-data (time stamps) of the 2244 object. For this reason, an exclusive object create may not 2245 include initial attributes because the server would have nowhere 2246 to store the verifier. 2248 If the server can not support these exclusive create semantics, 2249 possibly because of the requirement to commit the verifier to 2250 stable storage, it should fail the CREATE request with the error, 2251 NFS4ERR_NOTSUPP. 2253 During an exclusive CREATE request, if the object already exists, 2254 the server reconstructs the object's verifier and compares it with 2255 the verifier in the request. If they match, the server treats the 2256 request as a success. The request is presumed to be a duplicate of 2257 an earlier, successful request for which the reply was lost and 2258 that the server duplicate request cache mechanism did not detect. 2259 If the verifiers do not match, the request is rejected with the 2260 status, NFS4ERR_EXIST. 2262 Draft Protocol Specification NFS version 4 February 1999 2264 Once the client has performed a successful exclusive create, it 2265 must issue a SETATTR to set the correct object attributes. Until 2266 it does so, it should not rely upon any of the object attributes, 2267 since the server implementation may need to overload object meta- 2268 data to store the verifier. 2270 Use of the GUARDED attribute does not provide exactly-once 2271 semantics. In particular, if a reply is lost and the server does 2272 not detect the retransmission of the request, the procedure can 2273 fail with NFS4ERR_EXIST, even though the create was performed 2274 successfully. 2276 Note: 2278 1. Need to determine an initial set of attributes 2279 that must be set, and a set of attributes that 2280 can optionally be set, on a per-filetype basis. 2281 For instance, if the filetype is a NF4BLK then 2282 the device attributes must be set. 2284 2. Need to consider the symbolic link path as 2285 an "attribute". No need for a READLINK op 2286 if this is so. Similarly, a filehandle could 2287 be defined as an attribute for LINK. 2289 3. The presence of a generic create for 2290 multiple file types makes the protocol 2291 easier to extend to new file types in 2292 a minor rev (without defining new ops) 2294 4. The specific exclusive create semantics can be 2295 removed if there is guaranteed support for extended 2296 attributes. The client could specify the verifier 2297 be stored in an extended attribute and then check 2298 the attribute value itself instead of relying on the 2299 server to do so. 2301 ERRORS 2303 NFS4ERR_IO 2305 NFS4ERR_ACCES 2307 NFS4ERR_EXIST 2309 NFS4ERR_NOTDIR 2311 Draft Protocol Specification NFS version 4 February 1999 2313 NFS4ERR_NOSPC 2315 NFS4ERR_ROFS 2317 NFS4ERR_NAMETOOLONG 2319 NFS4ERR_DQUOT 2321 NFS4ERR_NOTSUPP 2323 NFS4ERR_SERVERFAULT 2325 Draft Protocol Specification NFS version 4 February 1999 2327 11.6. Procedure 5: GETATTR - Get attributes 2329 SYNOPSIS 2331 (cfh), attrbits -> attrbits, attrvals 2333 ARGS 2335 attrbits: bitmap 2337 RESULTS 2339 attrbits: bitmap 2341 attrvals: sequence of attributes 2343 DESCRIPTION 2345 Obtain attributes from the server. The client sets a bit in the 2346 bitmap argument for each attribute value that it would like the 2347 server to return. The server returns an attribute bitmap that 2348 indicates the attribute values that it was able to return, 2349 followed by the attribute values ordered lowest attribute number 2350 first. 2352 The server must return a value for each attribute that the client 2353 requests if the attribute is supported by the server. If the 2354 server does not support an attribute or cannot approximate a 2355 useful value then it must not return the attribute value and must 2356 not set the attribute bit in the result bitmap. The server must 2357 return an error if it supports an attribute but cannot obtain its 2358 value. In that case no attribute values will be returned. 2360 All servers must support attribute 0 which is a bitmap of all 2361 supported attributes for the filesystem object. 2363 IMPLEMENTATION 2365 ? 2367 ERRORS 2369 NFS4ERR_IO 2371 NFS4ERR_SERVERFAULT 2373 Draft Protocol Specification NFS version 4 February 1999 2375 11.7. Procedure 6: GETFH - Get current filehandle 2377 SYNOPSIS 2379 (cfh) -> filehandle 2381 ARGS 2383 RESULTS 2385 filehandle: filehandle 2387 DESCRIPTION 2389 Returns the current filehandle. Operations that change the 2390 current filehandle like LOOKUP or CREATE to not automatically 2391 return the new filehandle as a result. For instance, if a client 2392 needs to lookup a directory entry and obtain its filehandle then 2393 the following request will do it: 2395 1: PUTFH (directory filehandle) 2396 2: LOOKUP (entry name) 2397 3: GETFH 2399 IMPLEMENTATION 2401 ? 2403 ERRORS 2405 NFS4ERR_SERVERFAULT 2407 Draft Protocol Specification NFS version 4 February 1999 2409 11.8. Procedure 7: LINK - Create link to an object 2411 SYNOPSIS 2413 (cfh), dir, newname -> (cfh) 2415 ARGS 2417 dir: filehandle 2419 newname: utf8string 2421 RESULTS 2423 (none) 2425 DESCRIPTION 2427 Procedure LINK creates an additional newname for the file with the 2428 current filehandle in the new directory dir file and link.dir must 2429 reside on the same file system and server. On entry, the arguments 2430 in LINK3args are: 2432 IMPLEMENTATION 2434 Changes to any property of the hard-linked files are reflected in 2435 all of the linked files. When a hard link is made to a file, the 2436 attributes for the file should have a value for nlink that is one 2437 greater than the value before the LINK. 2439 The comments under RENAME regarding object and target residing on 2440 the same file system apply here as well. The comments regarding 2441 the target name applies as well. 2443 ERRORS 2445 NFS4ERR_IO 2447 NFS4ERR_ACCES 2449 NFS4ERR_EXIST 2451 NFS4ERR_XDEV 2453 NFS4ERR_NOTDIR 2455 Draft Protocol Specification NFS version 4 February 1999 2457 NFS4ERR_INVAL 2459 NFS4ERR_NOSPC 2461 NFS4ERR_ROFS 2463 NFS4ERR_MLINK 2465 NFS4ERR_NAMETOOLONG 2467 NFS4ERR_DQUOT 2469 NFS4ERR_NOTSUPP 2471 NFS4ERR_SERVERFAULT 2473 Draft Protocol Specification NFS version 4 February 1999 2475 11.9. Procedure 8: LOCK - Create lock 2477 SYNOPSIS 2479 (cfh) type, seqid, reclaim, owner, offset, length -> stateid, 2480 access 2482 ARGS 2484 type: {READ, WRITE, READW, WRITEW} 2486 seqid: uint32 2488 reclaim: boolean 2490 owner: nfs_lockowner 2492 offset: uint64 2494 length: uint64 2496 RESULTS 2498 stateid: uint64 2500 access: int 2502 DESCRIPTION 2503 The LOCK procedure requests that a record lock starting at 2504 'offset' for length 'length' be set on the file represented by 2505 'cfh'. The integer. The 'reclaim' field is used for failure 2506 recovery. 2508 IMPLEMENTATION 2509 See locking section for now. 2511 ERRORS 2512 To be determined. 2514 Draft Protocol Specification NFS version 4 February 1999 2516 11.10. Procedure 9: LOCKT - test for lock 2518 SYNOPSIS 2520 (cfh) type, seqid, reclaim, owner, offset, length -> {void, 2521 NFS4ERR_DENIED -> owner} 2523 ARGStype: {READ, WRITE, READW, WRITEW} 2525 seqid: uint32 2527 reclaim: boolean 2529 owner: nfs_lockowner 2531 offset: uint64 2533 length: uint64 2535 RESULTS 2537 owner: nfs_lockowner 2539 DESCRIPTION 2541 The LOCKT procedure tests the lock specified by the parameters. 2542 The owner of the lock is returned in the event it is currently 2543 being held; if no lock is held, nothing other than NFS4_OK is 2544 returned. 2546 ERRORS 2548 NFS4ERR_DENIED 2550 Draft Protocol Specification NFS version 4 February 1999 2552 11.11. Procedure 10: LOCKU - Unlock file 2554 SYNOPSIS 2556 (cfh) type, seqid, reclaim, owner, offset, length -> stateid 2558 ARGS 2560 type: {READ, WRITE, READW, WRITEW} 2562 seqid: uint32 2564 reclaim: boolean 2566 owner: nfs_lockowner 2568 offset: uint64 2570 length: uint64 2572 RESULTS 2574 stateid: uint64 2576 DESCRIPTION 2578 The LOCKU procedure unlocks the record lock specified by the 2579 parameters. 2581 ERRORS 2582 To be determined. 2584 Draft Protocol Specification NFS version 4 February 1999 2586 11.12. Procedure 11: LOOKUP - Lookup filename 2588 SYNOPSIS 2590 (cfh), filenames -> (cfh) 2592 ARGS 2594 filename: utf8string[] 2596 RESULTS 2598 (none) 2600 DESCRIPTION 2602 The current filehandle is assumed to refer to a directory. LOOKUP 2603 evaluates the pathname contained in the array of names and obtains 2604 a new current filehandle from the final name. All but the final 2605 name in the list must be the names of directories. 2607 If the pathname cannot be evaluated either because a component 2608 doesn't exist or because the client doesn't have permission to 2609 evaluate a component of the path, then an error will be returned 2610 and the current filehandle will be unchanged. 2612 IMPLEMENTATION 2614 If the client prefers a partial evaluation of the path then a 2615 sequence of LOOKUP operations can be substituted e.g. 2617 1. PUTFH (directory filehandle) 2618 2. LOOKUP "pub" "foo" "bar" 2619 3. GETFH 2621 or 2623 1. PUTFH (directory filehandle) 2624 2. LOOKUP "pub" 2625 3. GETFH 2626 4. LOOKUP "foo" 2627 5. GETFH 2628 6. LOOKUP "bar" 2629 7. GETFH 2631 NFS version 4 servers depart from the semantics of previous NFS 2632 versions in allowing LOOKUP requests to cross mountpoints on the 2634 Draft Protocol Specification NFS version 4 February 1999 2636 server. The client can detect a mountpoint crossing by comparing 2637 the fsid attribute of the directory with the fsid attribute of the 2638 directory looked up. If the fsids are different then the new 2639 directory is a server mountpoint. Unix clients that detect a 2640 mountpoint crossing will need to mount the server's filesystem. 2642 Servers that limit NFS access to "shares" or "exported" 2643 filesystems should provide a pseudo-filesystem into which the 2644 exported filesystems can be integrated, so that clients can browse 2645 the server's namespace. The clients view of a pseudo filesystem 2646 will be limited to paths that lead to exported filesystems. 2648 Note: previous versions of the protocol assigned special semantics 2649 to the names "." and "..". NFS version 4 assigns no special 2650 semantics to these names. The LOOKUPP operator must be used to 2651 lookup a parent directory. 2653 Note that this procedure does not follow symbolic links. The 2654 client is responsible for all parsing of filenames including 2655 filenames that are modified by symbolic links encountered during 2656 the lookup process. 2658 ERRORS 2660 NFS4ERR_IO 2662 NFS4ERR_NOENT 2664 NFS4ERR_ACCES 2666 NFS4ERR_NOTDIR 2668 NFS4ERR_NAMETOOLONG 2670 NFS4ERR_SERVERFAULT 2672 SEE 2674 CREATE 2676 Draft Protocol Specification NFS version 4 February 1999 2678 11.13. Procedure 12: LOOKUPP - Lookup parent directory 2680 SYNOPSIS 2682 (cfh) -> (cfh) 2684 ARGS 2686 (none) 2688 RESULTS 2690 (none) 2692 DESCRIPTION 2694 The current filehandle is assumed to refer to a directory. 2695 LOOKUPP assigns the filehandle for its parent directory to be the 2696 current filehandle. If there is no parent directory an ENOENT 2697 error must be returned. 2699 IMPLEMENTATION 2701 As for LOOKUP, LOOKUPP will also cross mountpoints. 2703 ERRORS 2705 NFS4ERR_IO 2707 NFS4ERR_NOENT 2709 NFS4ERR_ACCES 2711 NFS4ERR_SERVERFAULT 2713 SEE 2715 CREATE 2717 Draft Protocol Specification NFS version 4 February 1999 2719 11.14. Procedure 13: NVERIFY - Verify attributes different 2721 SYNOPSIS 2723 (cfh), attrbits, attrvals -> - 2725 ARGS 2727 attrbits: bitmap 2729 attrvals: sequence of attributes 2731 RESULTS 2733 (none) 2735 DESCRIPTION 2737 This operation is used to prefix a sequence of operations to be 2738 performed if one or more attributes have changed on some 2739 filesystem object. If all the attributes match then the error 2740 NFS4ERR_SAME must be returned. 2742 IMPLEMENTATION 2744 This operation is useful as a cache validation operator. If the 2745 object to which the attributes belong has changed then the 2746 following operations may obtain new data associated with that 2747 object. For instance, to check if a file has been changed and 2748 obtain new data if it has: 2750 1. PUTFH (public) 2751 2. LOOKUP "pub" "foo" "bar" 2752 3. NVERIFY attrbits attrs 2753 4. READ 0 32767 2755 ERRORS 2757 NFS4ERR_IO 2759 NFS4ERR_ACCES 2761 NFS4ERR_SERVERFAULT 2763 NFS4ERR_SAME 2765 Draft Protocol Specification NFS version 4 February 1999 2767 11.15. Procedure 14: OPEN - Open a regular file 2769 SYNOPSIS 2771 (cfh) filename, flag, owner, seqid, reclaim, access, deny -> 2772 stateid, access 2774 ARGS 2776 filename: utf8string 2778 flag: openflag (union (createhow4, void)) 2780 owner: nfs_lockowner 2782 seqid: uint32 2784 reclaim: boolean 2786 access: int (flag) 2788 deny: int (flag) 2790 RESULTS 2792 stateid: uint64 2794 access: int 2796 DESCRIPTION 2798 OPEN 2800 Procedure OPEN creates and/or opens a regular file in a directory 2801 with a given name. The flag determines if the file should be 2802 created if it does not exist and the how union contains a value of 2803 UNCHECKED, GUARDED, or EXCLUSIVE. UNCHECKED means that the file 2804 should be created without checking for the existence of a 2805 duplicate object in the same directory. In this case, attrbits and 2806 attrvals describe the initial attributes for the file. GUARDED 2807 specifies that the server should check for the presence of a 2808 duplicate object before performing the create and should fail the 2809 request with NFS4ERR_EXIST if a duplicate object exists. If the 2810 object does not exist, the request is performed as described for 2811 UNCHECKED. EXCLUSIVE specifies that the server is to follow 2812 exclusive creation semantics, using the verifier to ensure 2813 exclusive creation of the target. No attributes may be provided in 2815 Draft Protocol Specification NFS version 4 February 1999 2817 this case, since the server may use the target object meta-data to 2818 store the verifier. 2820 The current filehandle is replaced by that of the new object. 2822 IMPLEMENTATION 2823 The OPEN procedure carries support for EXCLUSIVE create forward 2824 from NFS version 3. As in NFS version 3, this mechanism provides 2825 reliable exclusive creation. Exclusive create is invoked when the 2826 how parameter is EXCLUSIVE. In this case, the client provides a 2827 verifier that can reasonably be expected to be unique. A 2828 combination of a client identifier, perhaps the client network 2829 address, and a unique number generated by the client, perhaps the 2830 RPC transaction identifier, may be appropriate. 2832 If the object does not exist, the server creates the object and 2833 stores the verifier in stable storage. For file systems that do 2834 not provide a mechanism for the storage of arbitrary file 2835 attributes, the server may use one or more elements of the object 2836 meta-data to store the verifier. The verifier must be stored in 2837 stable storage to prevent erroneous failure on retransmission of 2838 the request. It is assumed that an exclusive create is being 2839 performed because exclusive semantics are critical to the 2840 application. Because of the expected usage, exclusive CREATE does 2841 not rely solely on the normally volatile duplicate request cache 2842 for storage of the verifier. The duplicate request cache in 2843 volatile storage does not survive a crash and may actually flush 2844 on a long network partition, opening failure windows. In the UNIX 2845 local file system environment, the expected storage location for 2846 the verifier on creation is the meta-data (time stamps) of the 2847 object. For this reason, an exclusive object create may not 2848 include initial attributes because the server would have nowhere 2849 to store the verifier. 2851 If the server can not support these exclusive create semantics, 2852 possibly because of the requirement to commit the verifier to 2853 stable storage, it should fail the OPEN request with the error, 2854 NFS4ERR_NOTSUPP. 2856 During an exclusive CREATE request, if the object already exists, 2857 the server reconstructs the object's verifier and compares it with 2858 the verifier in the request. If they match, the server treats the 2859 request as a success. The request is presumed to be a duplicate of 2860 an earlier, successful request for which the reply was lost and 2861 that the server duplicate request cache mechanism did not detect. 2862 If the verifiers do not match, the request is rejected with the 2863 status, NFS4ERR_EXIST. 2865 Draft Protocol Specification NFS version 4 February 1999 2867 Once the client has performed a successful exclusive create, it 2868 must issue a SETATTR to set the correct object attributes. Until 2869 it does so, it should not rely upon any of the object attributes, 2870 since the server implementation may need to overload object meta- 2871 data to store the verifier. 2873 Use of the GUARDED attribute does not provide exactly-once 2874 semantics. In particular, if a reply is lost and the server does 2875 not detect the retransmission of the request, the procedure can 2876 fail with NFS4ERR_EXIST, even though the create was performed 2877 successfully. 2879 Note: Need to determine an initial set of attributes that 2880 must be set, and a set of attributes that can optionally be 2881 set. 2883 ERRORS 2885 NFS4ERR_IO 2887 NFS4ERR_ACCES 2889 NFS4ERR_EXIST 2891 NFS4ERR_NOTDIR 2893 NFS4ERR_NOSPC 2895 NFS4ERR_ROFS 2897 NFS4ERR_NAMETOOLONG 2899 NFS4ERR_DQUOT 2901 NFS4ERR_NOTSUPP 2903 NFS4ERR_SERVERFAULT 2905 Draft Protocol Specification NFS version 4 February 1999 2907 11.16. Procedure 15: PUTFH - Set current filehandle 2909 SYNOPSIS 2911 filehandle -> (cfh) 2913 ARGS 2915 filehandle: filehandle 2917 RESULTS 2918 (none) 2920 DESCRIPTION 2922 Replaces the current filehandle with the filehandle provided as an 2923 argument. If no filehandle has previously been installed as the 2924 current filehandle then root filehandle is assumed. If the length 2925 of the filehandle is zero, it is recognized by the server as a 2926 "public" filehandle. 2928 IMPLEMENTATION 2930 Commonly used as the first operator in any NFS request to set the 2931 context for following operations. 2933 ERRORS 2935 NFS4ERR_BADHANDLE 2937 NFS4ERR_SERVERFAULT 2939 Draft Protocol Specification NFS version 4 February 1999 2941 11.17. Procedure 16: PUTROOTFH - Set root filehandle 2943 SYNOPSIS 2945 - -> (cfh) 2947 ARGS 2949 (none) 2951 RESULTS 2953 (none) 2955 DESCRIPTION 2957 Replaces the current filehandle with the filehandle that 2958 represents the root of the server's namespace. From this 2959 filehandle a LOOKUP operation can locate any other filehandle on 2960 the server. This filehandle may be different from the "public" 2961 filehandle which may be associated with some other directory on 2962 the server. 2964 IMPLEMENTATION 2966 Commonly used as the first operator in any NFS request to set the 2967 context for following operations. 2969 ERRORS 2971 NFS4ERR_SERVERFAULT 2973 Draft Protocol Specification NFS version 4 February 1999 2975 11.18. Procedure 17: READ - Read from file 2977 SYNOPSIS 2979 (cfh), offset, count, stateid -> eof, data 2981 ARGS 2983 offset: uint64 2985 count: uint32 2987 stateid: uint64 2989 RESULTS 2991 eof: bool 2993 data: opaque <> 2995 DESCRIPTION 2997 READ reads data from the file identified by the current 2998 filehandle. 3000 offset 3002 The position within the file at which the read is to begin. 3003 An offset of 0 means to read data starting at the beginning 3004 of the file. If offset is greater than or equal to the size 3005 of the file, the status, NFS4_OK, is returned with count set 3006 to 0 and eof set to TRUE, subject to access permissions 3007 checking. 3009 count 3011 The number of bytes of data that are to be read. If count is 3012 0, the READ will succeed and return 0 bytes of data, subject 3013 to access permissions checking. count must be less than or 3014 equal to the value of the rtmax for the file system that 3015 contains file. If greater, the server may return only rtmax 3016 bytes, resulting in a short read. 3018 stateid 3020 The stateid returned from a previous record or share lock 3021 request. Used by the server to verify that the associated 3023 Draft Protocol Specification NFS version 4 February 1999 3025 lock is still valid and to update lease timeouts for the 3026 client. 3028 If the operation is successful the results are: 3030 eof 3032 If the read ended at the end-of-file (formally, in a 3033 correctly formed READ request, if offset + count is equal to 3034 the size of the file), eof is returned as TRUE; otherwise it 3035 is FALSE. A successful READ of an empty file will always 3036 return eof as TRUE. 3038 data 3040 The counted data read from the file. 3042 IMPLEMENTATION 3044 It is possible for the server to return fewer than count bytes of 3045 data. If the server returns less than the count requested and eof 3046 set to FALSE, the client should issue another READ to get the 3047 remaining data. A server may return less data than requested under 3048 several circumstances. The file may have been truncated by another 3049 client or perhaps on the server itself, changing the file size 3050 from what the requesting client believes to be the case. This 3051 would reduce the actual amount of data available to the client. It 3052 is possible that the server may back off the transfer size and 3053 reduce the read request return. Server resource exhaustion may 3054 also occur necessitating a smaller read return. 3056 If the file is locked the server will return an NFS4ERR_LOCKED 3057 error. Since the lock may be of short duration, the client may 3058 choose to retransmit the READ request (with exponential backoff) 3059 until the operation succeeds. 3061 ERRORS 3063 NFS4ERR_IO 3065 NFS4ERR_NXIO 3067 NFS4ERR_ACCES 3069 NFS4ERR_INVAL 3071 NFS4ERR_LOCKED 3073 Draft Protocol Specification NFS version 4 February 1999 3075 NFS4ERR_SERVERFAULT 3077 Draft Protocol Specification NFS version 4 February 1999 3079 11.19. Procedure 18: READDIR - Read directory 3081 SYNOPSIS 3082 (cfh), cookie, dircount, maxcount, attrbits -> { cookie, filename, 3083 attrbits, attributes }... 3085 ARGS 3087 cookie: uint64 3089 This should be set to 0 in the first request to read the 3090 directory. On subsequent requests, it should be a cookie as 3091 returned by the server. 3093 dircount: uint32 3095 The maximum number of bytes of directory information 3096 returned. This number should not include the size of the 3097 attributes and file handle portions of the result. 3099 maxcount: uint32 3101 The maximum size of the result in bytes. The size must 3102 include all XDR overhead. The server is free to return less 3103 than count bytes of data. 3105 attrbits: bitmap 3107 The attributes to be returned for each directory entry. 3109 RESULTS 3111 A list of directory entries. Each entry contains: 3113 cookie: uint64 3115 A value recognized by the server as a "bookmark" into the 3116 directory. It may be an offset or an index into a table. 3117 Ideally, the cookie value should not change if the directory 3118 is modified. 3120 filename: utf8string; 3122 The name of the directory entry. 3124 attrbits: bitmap 3126 Draft Protocol Specification NFS version 4 February 1999 3128 A bitmap that indicates which attributes follow. Ideally 3129 this bitmap will be identical to the attribute bitmap in the 3130 arguments, i.e. the server returns everything the client 3131 asked for. However, the returned bitmap may be different if 3132 the server does not support the attribute or if the attribute 3133 is not valid for the filetype. 3135 Note: need to consider the file handle as an "attribute" 3136 that may be optionally returned. The concept of file handle 3137 as attribute might also be useful for the CREATE of a hard 3138 link. 3140 DESCRIPTION 3142 Procedure READDIR retrieves a variable number of entries from a 3143 file system directory and returns complete information about each 3144 entry along with information to allow the client to request 3145 additional directory entries in a subsequent READDIR. 3147 IMPLEMENTATION 3149 Issues that need to be understood for this procedure include 3150 increased cache flushing activity on the client (as new file 3151 handles are returned with names which are entered into caches) and 3152 over-the-wire overhead versus expected subsequent LOOKUP and 3153 GETATTR elimination. 3155 The dircount and maxcount fields are included as an optimization. 3156 Consider a READDIR call on a UNIX operating system implementation 3157 for 1048 bytes; the reply does not contain many entries because of 3158 the overhead due to attributes and file handles. An alternative is 3159 to issue a READDIR call for 8192 bytes and then only use the first 3160 1048 bytes of directory information. However, the server doesn't 3161 know that all that is needed is 1048 bytes of directory 3162 information (as would be returned by READDIR). It sees the 8192 3163 byte request and issues a VOP_READDIR for 8192 bytes. It then 3164 steps through all of those directory entries, obtaining attributes 3165 and file handles for each entry. When it encodes the result, the 3166 server only encodes until it gets 8192 bytes of results which 3167 include the attributes and file handles. Thus, it has done a 3168 larger VOP_READDIR and many more attribute fetches than it needed 3169 to. The ratio of the directory entry size to the size of the 3170 attributes plus the size of the file handle is usually at least 8 3171 to 1. The server has done much more work than it needed to. 3173 The solution to this problem is for the client to provide two 3174 counts to the server. The first is the number of bytes of 3176 Draft Protocol Specification NFS version 4 February 1999 3178 directory information that the client really wants, dircount. The 3179 second is the maximum number of bytes in the result, including the 3180 attributes and file handles, maxcount. Thus, the server will issue 3181 a VOP_READDIR for only the number of bytes that the client really 3182 wants to get, not an inflated number. This should help to reduce 3183 the size of VOP_READDIR requests on the server, thus reducing the 3184 amount of work done there, and to reduce the number of VOP_LOOKUP, 3185 VOP_GETATTR, and other calls done by the server to construct 3186 attributes and file handles. 3188 ERRORS 3190 NFS4ERR_IO 3192 NFS4ERR_ACCES 3194 NFS4ERR_NOTDIR 3196 NFS4ERR_BAD_COOKIE 3198 NFS4ERR_TOOSMALL 3200 NFS4ERR_NOTSUPP 3202 NFS4ERR_SERVERFAULT 3204 Draft Protocol Specification NFS version 4 February 1999 3206 11.20. Procedure 19: READLINK - Read symbolic link 3208 SYNOPSIS 3210 (cfh) -> linktext 3212 ARGS 3214 (none) 3216 RESULTS 3218 linktext: utf8string 3220 DESCRIPTION 3222 READLINK reads the data associated with a symbolic link. The data 3223 is a UTF-8 string that is opaque to the server. That is, whether 3224 created by an NFS client or created locally on the server, the 3225 data in a symbolic link is not interpreted when created, but is 3226 simply stored. 3228 IMPLEMENTATION 3230 A symbolic link is nominally a pointer to another file. The data 3231 is not necessarily interpreted by the server, just stored in the 3232 file. It is possible for a client implementation to store a path 3233 name that is not meaningful to the server operating system in a 3234 symbolic link. A READLINK operation returns the data to the 3235 client for interpretation. If different implementations want to 3236 share access to symbolic links, then they must agree on the 3237 interpretation of the data in the symbolic link. 3239 The READLINK operation is only allowed on objects of type, NFLNK. 3240 The server should return the error, NFS4ERR_INVAL, if the object 3241 is not of type, NFLNK. 3243 ERRORS 3245 NFS4ERR_IO 3247 NFS4ERR_INVAL 3249 NFS4ERR_ACCES 3251 NFS4ERR_NOTSUPP 3253 Draft Protocol Specification NFS version 4 February 1999 3255 NFS4ERR_SERVERFAULT 3257 Draft Protocol Specification NFS version 4 February 1999 3259 11.21. Procedure 20: REMOVE - Remove filesystem object 3261 SYNOPSIS 3263 (cfh), filename -> - 3265 ARGS 3267 entryname: utf8string 3269 RESULTS 3271 (none) 3273 DESCRIPTION 3275 REMOVE removes (deletes) a directory entry named by filename from 3276 the directory corresponding to the current filehandle. If the 3277 entry in the directory was the last reference to the corresponding 3278 file system object, the object may be destroyed. 3280 IMPLEMENTATION 3282 NFS versions 2 and 3 required a different operator RMDIR for 3283 directory removal. NFS version 4 REMOVE can be used to delete any 3284 directory entry independent of its filetype. 3286 The concept of last reference is server specific. However, if the 3287 nlink field in the previous attributes of the object had the value 3288 1, the client should not rely on referring to the object via a 3289 file handle. Likewise, the client should not rely on the resources 3290 (disk space, directory entry, and so on.) formerly associated with 3291 the object becoming immediately available. Thus, if a client needs 3292 to be able to continue to access a file after using REMOVE to 3293 remove it, the client should take steps to make sure that the file 3294 will still be accessible. The usual mechanism used is to use 3295 RENAME to rename the file from its old name to a new hidden name. 3297 ERRORS 3299 NFS4ERR_NOENT 3301 NFS4ERR_IO 3303 NFS4ERR_ACCES 3305 NFS4ERR_NOTDIR 3307 Draft Protocol Specification NFS version 4 February 1999 3309 NFS4ERR_NAMETOOLONG 3311 NFS4ERR_ROFS 3313 NFS4ERR_NOTEMPTY 3315 NFS4ERR_SERVERFAULT 3317 Draft Protocol Specification NFS version 4 February 1999 3319 11.22. Procedure 21: RENAME - Rename directory entry 3321 SYNOPSIS 3323 (cfh), oldname, newdir, newname -> - 3325 ARGS 3327 oldname: utf8string 3329 newdir: filehandle 3331 newname: utf8string 3333 RESULTS 3335 status: uint32 3337 DESCRIPTION 3339 RENAME renames the directory identified by oldname in the 3340 directory corresponding to the current filehandle to newname in 3341 directory newdir. The operation is required to be atomic to the 3342 client. Source and target directories must reside on the same file 3343 system on the server. 3345 If the directory, newdir, already contains an entry with the name, 3346 newname, the source object must be compatible with the target: 3347 either both are non-directories or both are directories and the 3348 target must be empty. If compatible, the existing target is 3349 removed before the rename occurs. If they are not compatible or if 3350 the target is a directory but not empty, the server should return 3351 the error, NFS4ERR_EXIST. 3353 IMPLEMENTATION 3355 The RENAME operation must be atomic to the client. The statement 3356 "source and target directories must reside on the same file system 3357 on the server" means that the fsid fields in the attributes for 3358 the directories are the same. If they reside on different file 3359 systems, the error, NFS4ERR_XDEV, is returned. Even though the 3360 operation is atomic, the status, NFS4ERR_MLINK, may be returned if 3361 the server used a "unlink/link/unlink" sequence internally. 3363 A file handle may or may not become stale on a rename. However, 3364 server implementors are strongly encouraged to attempt to keep 3365 file handles from becoming stale in this fashion. 3367 Draft Protocol Specification NFS version 4 February 1999 3369 On some servers, the filenames, "." and "..", are illegal as 3370 either oldname or newname. In addition, neither oldname nor 3371 newname can be an alias for the source directory. These servers 3372 will return the error, NFS4ERR_INVAL, in these cases. 3374 If oldname and newname both refer to the same file (they might be 3375 hard links of each other), then RENAME should perform no action 3376 and return success. 3378 ERRORS 3380 NFS4ERR_NOENT 3382 NFS4ERR_IO 3384 NFS4ERR_ACCES 3386 NFS4ERR_EXIST 3388 NFS4ERR_XDEV 3390 NFS4ERR_NOTDIR 3392 NFS4ERR_ISDIR 3394 NFS4ERR_INVAL 3396 NFS4ERR_NOSPC 3398 NFS4ERR_ROFS 3400 NFS4ERR_MLINK 3402 NFS4ERR_NAMETOOLONG 3404 NFS4ERR_NOTEMPTY 3406 NFS4ERR_DQUOT 3408 NFS4ERR_NOTSUPP 3410 NFS4ERR_SERVERFAULT 3412 Draft Protocol Specification NFS version 4 February 1999 3414 11.23. Procedure 22: RENEW - renew a lease 3416 SYNOPSIS 3418 stateid -> () 3420 ARGS 3422 stateid: uint64 length: uint64 3424 RESULTS 3426 none 3428 DESCRIPTION 3430 Renews all leases for the client associated with the stateid. 3432 ERRORS 3433 TDB 3435 Draft Protocol Specification NFS version 4 February 1999 3437 11.24. Procedure 23: RESTOREFH - Restore saved filehandle 3439 SYNOPSIS 3441 (sfh) -> (cfh) 3443 ARGS 3445 (none) 3447 RESULTS 3449 (none) 3451 DESCRIPTION 3453 Make the saved filehandle the current filehandle. If there is no 3454 saved filehandle then return an error NFS4ERR_INVAL. 3456 IMPLEMENTATION 3458 Operators like CREATE and LOOKUP use the current filehandle to 3459 represent a directory and replace it with a new filehandle. 3460 Assuming the previous filehandle was saved with a SAVEFH operator, 3461 the previous filehandle can be restored as the current filehandle. 3462 This is commonly used to obtain post-operation attributes for the 3463 directory, e.g. 3465 1. PUTFH (directory filehandle) 3466 2. SAVEFH 3467 3. GETATTR attrbits (pre-op dir attrs) 3468 4. CREATE optbits "foo" attrs 3469 5. GETATTR attrbits (file attributes) 3470 6. RESTOREFH 3471 7. GETATTR attrbits (post-op dir attrs) 3473 ERRORS 3475 NFS4ERR_SERVERFAULT 3477 Draft Protocol Specification NFS version 4 February 1999 3479 11.25. Procedure 24: SAVEFH - Save current filehandle 3481 SYNOPSIS 3483 (cfh) -> (sfh) 3485 ARGS 3487 (none) 3489 RESULTS 3491 (none) 3493 DESCRIPTION 3495 Save the current filehandle. If a previous filehandle was saved 3496 then it is no longer accessible. The saved filehandle can be 3497 restored as the current filehandle with the RESTOREFH operator. 3499 IMPLEMENTATION 3501 (see RESTOREFH) 3503 ERRORS 3505 NFS4ERR_SERVERFAULT 3507 Draft Protocol Specification NFS version 4 February 1999 3509 11.26. Procedure 25: SECINFO - Obtain Available Security 3511 SYNOPSIS 3513 (cfh), filename -> { secinfo } 3515 ARGS 3517 filename: utf8string 3519 RESULTS 3521 secinfo: secinfo 3522 This is a link list of security flavors available for the 3523 supplied file handle and filename. 3525 DESCRIPTION 3527 This procedure is used by the client to obtain a list of valid RPC 3528 authentication flavors for a specific file handle, file name pair. 3529 For the flavors, AUTH_NONE, AUTH_SYS, AUTH_DH, and AUTH_KRB4 no 3530 additional security information is returned. For a return value 3531 of AUTH_RPCSEC_GSS, a security triple is returned that contains 3532 the mechanism object id (as defined in [RFC2078]), the quality of 3533 protection (as defined in [RFC 2078]) and the service type (as 3534 defined in [RFC2203]). It is possible for SECINFO to return 3535 multiple entries with flavor equal to AUTH_RPCSEC_GSS with 3536 different security triple values. 3538 IMPLEMENTATION 3540 This procedure is expected to be used by the NFS client when the 3541 error value of NFS4ERR_WRONGSEC is returned from another NFS 3542 procedure. This signifies to the client that the server's 3543 security policy is different from what the client is currently 3544 using. At this point, the client is expected to obtain a list of 3545 possible security flavors and choose what best suits its policies. 3547 ERRORS 3549 NFS4ERR_NOENT 3551 NFS4ERR_IO 3553 NFS4ERR_ACCES 3555 NFS4ERR_NAMETOOLONG 3557 Draft Protocol Specification NFS version 4 February 1999 3559 NFS4ERR_STALE 3561 NFS4ERR_SERVERFAULT 3563 NFS4ERR_FHEXPIRED 3565 NFS4ERR_WRONGSEC 3567 Draft Protocol Specification NFS version 4 February 1999 3569 11.27. Procedure 26: SETATTR - Set attributes 3571 SYNOPSIS 3573 (cfh), attrbits, attrvals -> - 3575 ARGS 3577 attrbits: bitmap 3579 attrvals 3581 DESCRIPTION 3583 Procedure SETATTR changes one or more of the attributes of a file 3584 system object on the server. The new attributes are specified with 3585 a bitmap and the attributes that follow the bitmap in bit order. 3587 IMPLEMENTATION 3589 The file size attribute is used to request changes to the size of 3590 a file. A value of 0 causes the file to be truncated, a value less 3591 than the current size of the file causes data from new size to the 3592 end of the file to be discarded, and a size greater than the 3593 current size of the file causes logically zeroed data bytes to be 3594 added to the end of the file. Servers are free to implement this 3595 using holes or actual zero data bytes. Clients should not make any 3596 assumptions regarding a server's implementation of this feature, 3597 beyond that the bytes returned will be zeroed. Servers must 3598 support extending the file size via SETATTR. 3600 SETATTR is not guaranteed atomic. A failed SETATTR may partially 3601 change a file's attributes. 3603 Changing the size of a file with SETATTR indirectly changes the 3604 mtime. A client must account for this as size changes can result 3605 in data deletion. 3607 If server and client times differ, programs that compare client 3608 time to file times can break. A time maintenance protocol should 3609 be used to limit client/server time skew. 3611 If the server cannot successfully set all the attributes it must 3612 return an NFS4ERR_INVAL error. An error may be returned if the 3613 server can not store a uid or gid in its own representation of 3614 uids or gids, respectively. If the server can only support 32 bit 3615 offsets and sizes, a SETATTR request to set the size of a file to 3617 Draft Protocol Specification NFS version 4 February 1999 3619 larger than can be represented in 32 bits will be rejected with 3620 this same error. 3622 ERRORS 3624 NFS4ERR_PERM 3626 NFS4ERR_IO 3628 NFS4ERR_ACCES 3630 NFS4ERR_INVAL 3632 NFS4ERR_NOSPC 3634 NFS4ERR_ROFS 3636 NFS4ERR_DQUOT 3638 NFS4ERR_SERVERFAULT 3640 Draft Protocol Specification NFS version 4 February 1999 3642 11.28. Procedure 27: SETCLIENTID - negotiated clientid 3644 SYNOPSIS 3646 verifier, client -> clientid 3648 ARGS 3650 verifier: uint32 3652 client: opaque <> 3654 RESULTS 3656 clientid: uint64 3658 DESCRIPTION 3660 Procedure SETCLIENTID introduces the ability of the client to 3661 notify the server of its intention to use a particular client 3662 identifier and verifier pair. Upon successful completion the 3663 server will return a clientid which is used in subsequent file 3664 locking requests. 3666 IMPLEMENTATION 3668 The server takes the verifier and client identification supplied 3669 and search for a match of the client identification. If no match 3670 is found the server saves the principal/uid information along with 3671 the verifier and client identification and returns a unique 3672 clientid that is used as a short hand reference to the supplied 3673 information. 3675 If the server find matching client identification and a 3676 corresponding match in principal/uid, the server releases all 3677 locking state for the client and returns a new clientid. 3679 ERRORS 3680 TBD 3682 Draft Protocol Specification NFS version 4 February 1999 3684 11.29. Procedure 28: VERIFY - Verify attributes same 3686 SYNOPSIS 3688 (cfh), attrbits, attrvals -> - 3690 ARGS 3692 attrbits: bitmap 3694 attrvals 3696 RESULTS 3698 (none) 3700 DESCRIPTION 3702 This operation is used to verify that attributes have a value 3703 assumed by the client before proceeding with following operations 3704 in the compound request. For instance, a VERIFY can be used to 3705 make sure that the file size has not changed for an append-mode 3706 write: 3708 1. PUTFH 0x0123456 3709 2. VERIFY attrbits attrs 3710 3. WRITE 450328 4096 3712 If the attributes are not as expected, then the request fails and 3713 the data is not appended to the file. 3715 IMPLEMENTATION 3717 ERRORS 3719 Draft Protocol Specification NFS version 4 February 1999 3721 11.30. Procedure 29: WRITE - Write to file 3723 SYNOPSIS 3725 (cfh), offset, count, stability, stateid, data -> count, 3726 committed, verifier 3728 ARGS 3730 offset: uint64 3732 count: uint32 3734 stability: uint32 3736 stateid: uint64 3738 data: opaque 3740 RESULTS 3742 count: uint32 3744 committed: uint32 3746 verifier: uint32 3748 DESCRIPTION 3750 Write data to the file identified by the current filehandle. 3751 Arguments are as follows: 3753 offset 3755 The position within the file at which the write is to begin. 3756 An offset of 0 means to write data starting at the beginning 3757 of the file. 3759 count 3761 The number of bytes of data to be written. If count is 0, the 3762 WRITE will succeed and return a count of 0, barring errors 3763 due to permissions checking. The size of data must be less 3764 than or equal to the value of the wtmax attribute for the 3765 filesystem that contains file. If greater, the server may 3766 write only wtmax bytes, resulting in a short write. 3768 Draft Protocol Specification NFS version 4 February 1999 3770 stability 3772 If stable is FILE_SYNC, the server must commit the data 3773 written plus all file system metadata to stable storage 3774 before returning results. This corresponds to the NFS version 3775 2 protocol semantics. Any other behavior constitutes a 3776 protocol violation. If stable is DATA_SYNC, then the server 3777 must commit all of the data to stable storage and enough of 3778 the metadata to retrieve the data before returning. The 3779 server implementor is free to implement DATA_SYNC in the same 3780 fashion as FILE_SYNC, but with a possible performance drop. 3781 If stable is UNSTABLE, the server is free to commit any part 3782 of the data and the metadata to stable storage, including all 3783 or none, before returning a reply to the client. There is no 3784 guarantee whether or when any uncommitted data will 3785 subsequently be committed to stable storage. The only 3786 guarantees made by the server are that it will not destroy 3787 any data without changing the value of verf and that it will 3788 not commit the data and metadata at a level less than that 3789 requested by the client. 3791 stateid 3793 The stateid returned from a previous record or share lock 3794 request. Used by the server to verify that the associated 3795 lock is still valid and to update lease timeouts for the 3796 client. 3798 data 3800 The data to be written to the file. 3802 If the operation is successful the following results are returned: 3804 count 3806 The number of bytes of data written to the file. The server 3807 may write fewer bytes than requested. If so, the actual 3808 number of bytes written starting at location, offset, is 3809 returned. 3811 committed 3813 The server should return an indication of the level of 3814 commitment of the data and metadata via committed. If the 3815 server committed all data and metadata to stable storage, 3816 committed should be set to FILE_SYNC. If the level of 3817 commitment was at least as strong as DATA_SYNC, then 3819 Draft Protocol Specification NFS version 4 February 1999 3821 committed should be set to DATA_SYNC. Otherwise, committed 3822 must be returned as UNSTABLE. If stable was FILE_SYNC, then 3823 committed must also be FILE_SYNC: anything else constitutes a 3824 protocol violation. If stable was DATA_SYNC, then committed 3825 may be FILE_SYNC or DATA_SYNC: anything else constitutes a 3826 protocol violation. If stable was UNSTABLE, then committed 3827 may be either FILE_SYNC, DATA_SYNC, or UNSTABLE. 3829 verifier 3831 This is a cookie that the client can use to determine whether 3832 the server has changed state between a call to WRITE and a 3833 subsequent call to either WRITE or COMMIT. This cookie must 3834 be consistent during a single instance of the NFS version 4 3835 protocol service and must be unique between instances of the 3836 NFS version 4 protocol server, where uncommitted data may be 3837 lost. 3839 If a client writes data to the server with the stable argument set 3840 to UNSTABLE and the reply yields a committed response of DATA_SYNC 3841 or UNSTABLE, the client will follow up some time in the future 3842 with a COMMIT operation to synchronize outstanding asynchronous 3843 data and metadata with the server's stable storage, barring client 3844 error. It is possible that due to client crash or other error that 3845 a subsequent COMMIT will not be received by the server. 3847 IMPLEMENTATION 3849 It is possible for the server to write fewer than count bytes of 3850 data. In this case, the server should not return an error unless 3851 no data was written at all. If the server writes less than count 3852 bytes, the client should issue another WRITE to write the 3853 remaining data. 3855 It is assumed that the act of writing data to a file will cause 3856 the mtime of the file to be updated. However, the mtime of the 3857 file should not be changed unless the contents of the file are 3858 changed. Thus, a WRITE request with count set to 0 should not 3859 cause the mtime of the file to be updated. 3861 The definition of stable storage has been historically a point of 3862 contention. The following expected properties of stable storage 3863 may help in resolving design issues in the implementation. Stable 3864 storage is persistent storage that survives: 3866 Draft Protocol Specification NFS version 4 February 1999 3868 1. Repeated power failures. 3869 2. Hardware failures (of any board, power supply, etc.). 3870 3. Repeated software crashes, including reboot cycle. 3872 This definition does not address failure of the stable storage 3873 module itself. 3875 The verifier, is defined to allow a client to detect different 3876 instances of an NFS version 4 protocol server over which cached, 3877 uncommitted data may be lost. In the most likely case, the 3878 verifier allows the client to detect server reboots. This 3879 information is required so that the client can safely determine 3880 whether the server could have lost cached data. If the server 3881 fails unexpectedly and the client has uncommitted data from 3882 previous WRITE requests (done with the stable argument set to 3883 UNSTABLE and in which the result committed was returned as 3884 UNSTABLE as well) it may not have flushed cached data to stable 3885 storage. The burden of recovery is on the client and the client 3886 will need to retransmit the data to the server. 3888 A suggested verifier would be to use the time that the server was 3889 booted or the time the server was last started (if restarting the 3890 server without a reboot results in lost buffers). 3892 The committed field in the results allows the client to do more 3893 effective caching. If the server is committing all WRITE requests 3894 to stable storage, then it should return with committed set to 3895 FILE_SYNC, regardless of the value of the stable field in the 3896 arguments. A server that uses an NVRAM accelerator may choose to 3897 implement this policy. The client can use this to increase the 3898 effectiveness of the cache by discarding cached data that has 3899 already been committed on the server. 3901 Some implementations may return NFS4ERR_NOSPC instead of 3902 NFS4ERR_DQUOT when a user's quota is exceeded. 3904 ERRORS 3906 NFS4ERR_IO 3908 NFS4ERR_ACCES 3910 NFS4ERR_FBIG 3912 NFS4ERR_DQUOT 3914 Draft Protocol Specification NFS version 4 February 1999 3916 NFS4ERR_NOSPC 3918 NFS4ERR_ROFS 3920 NFS4ERR_INVAL 3922 NFS4ERR_LOCKED 3924 NFS4ERR_SERVERFAULT 3926 Draft Protocol Specification NFS version 4 February 1999 3928 12. Locking notes 3930 12.1. Short and long leases 3932 The usual lease trade-offs apply: short leases are good for fast 3933 server recovery at a cost of increased RENEW or READ (with zero 3934 length) requests. 3936 Longer leases are certainly kinder and gentler to large internet 3937 servers trying to handle huge numbers of clients. RENEW requests drop 3938 in direct proportion to the lease time. The disadvantages of long 3939 leases are slower server recover after crash (server must wait for 3940 leases to expire and grace period before granting new lock requests) 3941 and increased file contention (if client fails to transmit an unlock 3942 request then server must wait for lease expiration before granting 3943 new locks). 3945 Long leases are usable if the server is to store lease state in non- 3946 volatile memory. Upon recovery, the server can reconstruct the lease 3947 state from its non-volatile memory and continue operation with its 3948 clients and therefore long leases are not an issue. 3950 12.2. Clocks and leases 3952 To avoid the need for synchronized clocks, lease times are granted by 3953 the server as a time delta, though there is a requirement that the 3954 client and server clocks do not drift excessively over the duration 3955 of the lock. There is also the issue of propagation delay across the 3956 network which could easily be several hundred milliseconds across the 3957 Internet as well as the possibility that requests will be lost and 3958 need to be retransmitted. 3960 To take propagation delay into account, the client should subtract a 3961 it from lease times, e.g. if the client estimates the one-way 3962 propagation delay as 200 msec, then it can assume that the lease is 3963 already 200 msec old when it gets it. In addition, it'll take 3964 another 200 msec to get a response back to the server. So the client 3965 must send a lock renewal or write data back to the server 400 msec 3966 before the lease would expire. 3968 The client could measure propagation delay with reasonable accuracy 3969 by measuring the round-trip time for lock extensions assuming that 3970 there's not much server processing overhead in an extension. 3972 12.3. Locks and lease times 3974 Lock requests do not contain desired lease times. The server 3976 Draft Protocol Specification NFS version 4 February 1999 3978 allocates leases with no information from the client. The assumption 3979 here is that the client really has no idea of just how long the lock 3980 will be required. If a scenario can be found where a hint from the 3981 client as to the maximum lease time desired would be useful, then 3982 this feature could be added to lock requests. 3984 12.4. Locking of directories and other meta-files 3986 A question: should directories and/or other file-system objects like 3987 symbolic links be lockable ? Clients will want to cache whole 3988 directories. It would be nice to have consistent directory caches, 3989 but it would require that any client creating a new file get a write 3990 lock on the directory and be prepared to handle lock denial. Is the 3991 weak cache consistency that we currently have for directories 3992 acceptable ? I think perhaps it is - given the expense of doing full 3993 consistency on an Internet scale. 3995 12.5. Proxy servers and leases 3997 Proxy servers. There is some interest in having NFS V4 support 3998 caching proxies. Support for proxy caching is a requirement if 3999 servers are to handle large numbers of clients - clients that may 4000 have little or no ability to cache on their own. How could proxy 4001 servers use lease-based locking ? 4003 12.6. Locking and the new latency 4005 Latency caused by locking. If a client wants to update a file then 4006 it will have to wait until the leases on read locks have expired. If 4007 the leases are of the order of 60 seconds or several minutes then the 4008 client (and end-user) may be blocked for a while. This is unfamiliar 4009 for current NFS users who are not bothered by mandatory locking - but 4010 it could be an issue if we decide we like the caching benefits. A 4011 similar problem exists for clients that wish to read a file that is 4012 write locked. The read-lock case is likely to be more common if 4013 read-locking is used to protect cached data on the client. 4015 Draft Protocol Specification NFS version 4 February 1999 4017 13. Internationalization 4019 The primary issue in which NFS needs to deal with 4020 internationalization ,or i18n, is with respect to file names and 4021 other strings as used within the protocol. NFS' choice of string 4022 representation must allow reasonable name/string access to clients 4023 which use various languages. The UTF-8 encoding allows for this type 4024 of access and this choice is explained in the following. 4026 13.1. Universal Versus Local Character Sets 4028 [RFC1345] describes a table of 16 bit characters for many different 4029 languages (the bit encodings match Unicode, though of course RFC1345 4030 is somewhat out of date with respect to current Unicode assignments). 4031 Each character from each language has a unique 16 bit value in the 16 4032 bit character set. Thus this table can be thought of as a universal 4033 character set. [RFC1345] then talks about groupings of subsets of the 4034 entire 16 bit character set into "Charset Tables". For example one 4035 might take all the Greek characters from the 16 bit table (which are 4036 are consecutively allocated), and normalize their offsets to a table 4037 that fits in 7 bits. Thus we find that "lower case alpha" is in the 4038 same position as "upper case a" in the US-ASCII table, and "upper 4039 case alpha" is in the same position as "lower case a" in the US-ASCII 4040 table. 4042 These normalized subset character sets can be thought of as "local 4043 character sets", suitable for an operating system locale. 4045 Local character sets are not suitable for the NFS protocol. Consider 4046 someone who creates a file with a name in a Swedish character set. If 4047 someone else later goes to access the file with their locale set to 4048 the Swedish language, then there are no problems. But if someone in 4049 say the US-ASCII locale goes to access the file, the file name will 4050 look very different, because the Swedish characters in the 7 bit 4051 table will now be represented in US-ASCII characters on the display. 4052 It would be preferable to give the US-ASCII user a way to display the 4053 file name using Swedish glyphs. In order to do that, the NFS protocol 4054 would have to include the locale with the file name on each operation 4055 to create a file. 4057 But then what of the situation when we have a path name on the server 4058 like: 4060 /component-1/component-2/component-3 4062 Each component could have been created with a different locale. If 4063 one issues CREATE with multi-component path name, and if some of the 4064 leading components already exist, what is to be done with the 4066 Draft Protocol Specification NFS version 4 February 1999 4068 existing components? Is the current locale attribute replaced with 4069 the user's current one? These types of situations quickly become too 4070 complex when there is an alternate solution. 4072 If NFS V4 used a universal 16 bit or 32 bit character set (or a 4073 encoding of a 16 bit or 32 bit character set into octets), then 4074 server and client need not care if the locale of the user accessing 4075 the file is different than the locale of the user who created the 4076 file. The unique 16 bit or 32 bit encoding of the character allows 4077 for determination of what language the character is from and also how 4078 to display that character on the client. The server need not know 4079 what locales are used. 4081 13.2. Overview of Universal Character Set Standards 4083 The previous section makes a case for using a universal character set 4084 in NFS version 4. This section makes the case for using UTF-8 as the 4085 specific universal character set for NFS version 4. 4087 [RFC2279] discusses UTF-* (UTF-8 and other UTF-XXX encodings), 4088 Unicode, and UCS-*. There are two standards bodies managing universal 4089 code sets: 4091 o ISO/IEC which has the standard 10646-1 4093 o Unicode which has the Unicode standard 4095 Both standards bodies have pledged to track each other's assignments 4096 of character codes. 4098 The following is a brief analysis of the various standards. 4100 UCS Universal Character Set. This is ISO/IEC 10646-1: "a 4101 multi-octet character set called the Universal Character 4102 Set (UCS), which encompasses most of the world's writing 4103 systems." 4105 UCS-2 a two octet per character encoding that addresses the first 4106 2^16 characters of UCS. Currently there are no UCS 4107 characters beyond that range. 4109 UCS-4 a four octet per character encoding that permits the 4110 encoding of up to 2^31 characters. 4112 Draft Protocol Specification NFS version 4 February 1999 4114 UTF UCS transformation format. 4116 UTF-1 Only historical interest; it has been removed from 10646-1 4118 UTF-7 Encodes the entire "repertoire" of UCS "characters using 4119 only octets with the higher order bit clear". [RFC2152] 4120 describes UTF-7. UTF-7 accomplishes this by reserving one 4121 of the 7bit US-ASCII characters as a "shift" character to 4122 indicate non-US-ASCII characters. 4124 UTF-8 Unlike UTF-7, uses all 8 bits of the octets. US-ASCII 4125 characters are encoded as before unchanged. Any octet with 4126 the high bit cleared can only mean a US-ASCII character. 4127 The high bit set means that a UCS character is being 4128 encoded. 4130 UTF-16 Encodes UCS-4 characters into UCS-2 characters using a 4131 reserved range in UCS-2. 4133 Unicode Unicode and UCS-2 are the same; [RFC2279] states: 4135 Up to the present time, changes in Unicode and amendments 4136 to ISO/IEC 10646 have tracked each other, so that the 4137 character repertoires and code point assignments have 4138 remained in sync. The relevant standardization committees 4139 have committed to maintain this very useful synchronism. 4141 13.3. Difficulties with UCS-4, UCS-2, Unicode 4143 Adapting existing applications, and file systems to multi-octet 4144 schemes like UCS and Unicode can be difficult. A significant amount 4145 of code has been written to process streams of bytes. Also there are 4146 many existing stored objects described with 7 bit or 8 bit 4147 characters. Doubling or quadrupling the bandwidth and storage 4148 requirements seems like an expensive way to accomplish I18N. 4150 UCS-2 and Unicode are "only" 16 bits long. That might seem to be 4151 enough but, according to [Unicode1], 38,887 Unicode characters are 4152 already assigned. And according to [Unicode2] there are still more 4153 languages that need to be added. 4155 Draft Protocol Specification NFS version 4 February 1999 4157 13.4. UTF-8 and its solutions 4159 UTF-8 solves problems for NFS that exist with the use of UCS and 4160 Unicode. UTF-8 will encode 16 bit and 32 bit characters in a way 4161 that will be compact for most users. The encoding table from UCS-4 to 4162 UTF-8, as copied from [RFC2279]: 4164 UCS-4 range (hex.) UTF-8 octet sequence (binary) 4165 0000 0000-0000 007F 0xxxxxxx 4166 0000 0080-0000 07FF 110xxxxx 10xxxxxx 4167 0000 0800-0000 FFFF 1110xxxx 10xxxxxx 10xxxxxx 4169 0001 0000-001F FFFF 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx 4170 0020 0000-03FF FFFF 111110xx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 4171 0400 0000-7FFF FFFF 1111110x 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 4172 10xxxxxx 4174 See [RFC2279] for precise encoding and decoding rules. Note because 4175 of UTF-16, the algorithm from Unicode/UCS-2 to UTF-8 needs to account 4176 for the reserved range between D800 and DFFF. 4178 Note that the 16 bit UCS or Unicode characters require no more than 3 4179 octets to encode into UTF-8 4181 Interestingly, UTF-8 has room to handle characters larger than 31 4182 bits, because the leading octet of form: 4184 1111111x 4186 is not defined. If needed, ISO could either use that octet to 4187 indicate a sequence of an encoded 8 octet character, or perhaps use 4188 11111110 to permit the next octet to indicate an even more expandable 4189 character set. 4191 So using UTF-8 to represent character encodings means never having to 4192 run out of room. 4194 Draft Protocol Specification NFS version 4 February 1999 4196 14. Security Considerations 4198 The major security feature to consider is the authentication of the 4199 user making the request of NFS service. Consideration should also be 4200 given to the integrity and privacy of this NFS request. These 4201 specific issues are discussed as part of the section on "RPC and 4202 Security Flavor". 4204 As this document progresses, other issues of denial of service and 4205 other typical security issues will be addressed here along with those 4206 issues specific to NFS service. 4208 Draft Protocol Specification NFS version 4 February 1999 4210 15. NFS Version 4 RPC definition file 4212 /* 4213 * nfs_prot.x 4214 * 4215 */ 4217 %#pragma ident "@(#)nfs_prot.x 1.28 99/02/26" 4219 /* 4220 * Sizes 4221 */ 4222 const NFS4_FHSIZE = 128; 4223 const NFS4_CREATEVERFSIZE = 8; 4225 /* 4226 * Timeval 4227 */ 4228 struct nfstime4 { 4229 int64_t seconds; 4230 uint32_t nseconds; 4231 }; 4233 struct specdata4 { 4234 uint32_t specdata1; 4235 uint32_t specdata2; 4236 }; 4238 /* 4239 * Basic data types 4240 */ 4241 typedef opaque utf8string<>; 4242 typedef uint64_t offset4; 4243 typedef uint32_t count4; 4244 typedef uint32_t length4; 4245 typedef uint64_t clientid4; 4246 typedef uint64_t stateid4; 4247 typedef uint32_t seqid4; 4248 typedef uint32_t writeverf4; 4249 typedef opaque createverf4[NFS4_CREATEVERFSIZE]; 4250 typedef utf8string filename4; 4251 typedef uint64_t nfs_lockid4; 4252 typedef uint32_t nfs_lease4; 4253 typedef uint32_t nfs_lockstate4; 4254 typedef uint64_t nfs_cookie4; 4255 typedef utf8string linktext4; 4256 typedef opaque sec_oid4<>; 4257 typedef uint32_t qop4; 4259 Draft Protocol Specification NFS version 4 February 1999 4261 typedef uint32_t fattr4_type; 4262 typedef uint32_t fattr4_mode; 4263 typedef uint32_t fattr4_accessbits; 4264 typedef uint32_t fattr4_nlink; 4265 typedef utf8string fattr4_uid; 4266 typedef utf8string fattr4_gid; 4267 typedef uint64_t fattr4_size; 4268 typedef uint64_t fattr4_used; 4269 typedef specdata4 fattr4_rdev; 4270 typedef uint64_t fattr4_fsid; 4271 typedef uint64_t fattr4_fileid; 4272 typedef nfstime4 fattr4_atime; 4273 typedef nfstime4 fattr4_mtime; 4274 typedef nfstime4 fattr4_ctime; 4275 typedef uint32_t fattr4_rtmax; 4276 typedef uint32_t fattr4_rtpref; 4277 typedef uint32_t fattr4_rtmult; 4278 typedef uint32_t fattr4_wtmax; 4279 typedef uint32_t fattr4_wtpref; 4280 typedef uint32_t fattr4_wtmult; 4281 typedef uint32_t fattr4_dtpref; 4282 typedef uint64_t fattr4_maxfilesize; 4283 typedef uint64_t fattr4_change; 4284 typedef nfstime4 fattr4_time_delta; 4285 typedef uint32_t fattr4_properties; 4286 typedef uint32_t fattr4_linkmax; 4287 typedef uint32_t fattr4_name_max; 4289 /* 4290 * Error status 4291 */ 4292 enum nfsstat4 { 4293 NFS4_OK = 0, 4294 NFS4ERR_PERM = 1, 4295 NFS4ERR_NOENT = 2, 4296 NFS4ERR_IO = 5, 4297 NFS4ERR_NXIO = 6, 4298 NFS4ERR_ACCES = 13, 4299 NFS4ERR_EXIST = 17, 4300 NFS4ERR_XDEV = 18, 4301 NFS4ERR_NODEV = 19, 4302 NFS4ERR_NOTDIR = 20, 4303 NFS4ERR_ISDIR = 21, 4304 NFS4ERR_INVAL = 22, 4305 NFS4ERR_FBIG = 27, 4306 NFS4ERR_NOSPC = 28, 4307 NFS4ERR_ROFS = 30, 4308 NFS4ERR_MLINK = 31, 4310 Draft Protocol Specification NFS version 4 February 1999 4312 NFS4ERR_NAMETOOLONG = 63, 4313 NFS4ERR_NOTEMPTY = 66, 4314 NFS4ERR_DQUOT = 69, 4315 NFS4ERR_STALE = 70, 4316 NFS4ERR_BADHANDLE = 10001, 4317 NFS4ERR_NOT_SYNC = 10002, 4318 NFS4ERR_BAD_COOKIE = 10003, 4319 NFS4ERR_NOTSUPP = 10004, 4320 NFS4ERR_TOOSMALL = 10005, 4321 NFS4ERR_SERVERFAULT = 10006, 4322 NFS4ERR_BADTYPE = 10007, 4323 NFS4ERR_JUKEBOX = 10008, 4324 NFS4ERR_SAME = 10009, 4325 NFS4ERR_DENIED = 10010,/* lock unavailable */ 4326 NFS4ERR_EXPIRED = 10011,/* lock lease expired */ 4327 NFS4ERR_LOCKED = 10012,/* I/O failed due to lock */ 4328 NFS4ERR_GRACE = 10013,/* in grace period */ 4329 NFS4ERR_FHEXPIRED = 10014 /* file handle expired */ 4330 }; 4332 enum rpc_flavor4 { 4333 AUTH_NONE = 0, 4334 AUTH_SYS = 1, 4335 AUTH_DH = 2, 4336 AUTH_KRB4 = 3, 4337 AUTH_RPCSEC_GSS = 4 4338 }; 4340 /* 4341 * From RFC 2203 4342 */ 4343 enum rpc_gss_svc_t { 4344 RPC_GSS_SVC_NONE = 1, 4345 RPC_GSS_SVC_INTEGRITY = 2, 4346 RPC_GSS_SVC_PRIVACY = 3 4347 }; 4349 /* 4350 * File access handle 4351 */ 4352 struct nfs_fh4 { 4353 opaque data; 4354 }; 4356 /* 4357 * File types 4358 */ 4359 enum ftype4 { 4361 Draft Protocol Specification NFS version 4 February 1999 4363 NF4REG = 1, 4364 NF4DIR = 2, 4365 NF4BLK = 3, 4366 NF4CHR = 4, 4367 NF4LNK = 5, 4368 NF4SOCK = 6, 4369 NF4FIFO = 7 4370 }; 4372 const FATTR4_TYPE = 1; 4373 const FATTR4_MODE = 2; 4374 const FATTR4_ACCESSBITS = 3; 4375 const FATTR4_NLINK = 4; 4376 const FATTR4_UID = 5; 4377 const FATTR4_GID = 6; 4378 const FATTR4_SIZE = 7; 4379 const FATTR4_USED = 8; 4380 const FATTR4_RDEV = 9; 4381 const FATTR4_FSID = 10; 4382 const FATTR4_FILEID = 11; 4383 const FATTR4_ATIME = 12; 4384 const FATTR4_MTIME = 13; 4385 const FATTR4_CTIME = 14; 4386 const FATTR4_RTMAX = 15; 4387 const FATTR4_RTPREF = 16; 4388 const FATTR4_RTMULT = 17; 4389 const FATTR4_WTMAX = 18; 4390 const FATTR4_WTPREF = 19; 4391 const FATTR4_WTMULT = 20; 4392 const FATTR4_DTPREF = 21; 4393 const FATTR4_MAXFILESIZE = 22; 4394 const FATTR4_TIME_DELTA = 23; 4395 const FATTR4_PROPERTIES = 24; 4396 const FATTR4_LINKMAX = 25; 4397 const FATTR4_NAME_MAX = 26; 4398 const FATTR4_NO_TRUNC = 27; 4399 const FATTR4_CHOWN_RESTRICTED = 28; 4400 const FATTR4_CASE_INSENSITIVE = 29; 4401 const FATTR4_CASE_PRESERVING = 30; 4403 /* 4404 * fattr4_properties bits 4405 */ 4406 const FSF_LINK = 0x00000001; 4407 const FSF_SYMLINK = 0x00000002; 4408 const FSF_HOMOGENEOUS = 0x00000004; 4409 const FSF_CANSETTIME = 0x00000008; 4410 const FSF_NOTRUNC = 0x00000010; 4412 Draft Protocol Specification NFS version 4 February 1999 4414 const FSF_CHOWN_RESTRICTED = 0x00000020; 4415 const FSF_CASE_INSENSITIVE = 0x00000040; 4416 const FSF_CASE_PRESERVING = 0x00000080; 4418 struct bitmap4 { 4419 uint32_t bits<>; 4420 }; 4422 struct attrlist { 4423 opaque attrs<>; 4424 }; 4426 struct fattr4 { 4427 bitmap4 attrmask; 4428 attrlist attr_vals; 4429 }; 4431 struct cid { 4432 opaque verifier<4>; 4433 opaque id<>; 4434 }; 4436 union nfs_client_id switch (clientid4 clientid) { 4437 case 0: 4438 cid ident; 4439 default: 4440 void; 4441 }; 4443 struct lockown { 4444 clientid4 clientid; 4445 opaque owner<>; 4446 }; 4448 union nfs_lockowner switch (stateid4 stateid) { 4449 case 0: 4450 lockown ident; 4451 default: 4452 void; 4453 }; 4455 enum lock_type { 4456 READ = 1, 4457 WRITE = 2, 4458 READW = 3, /* blocking read */ 4459 WRITEW = 4 /* blocking write */ 4460 }; 4462 Draft Protocol Specification NFS version 4 February 1999 4464 /* 4465 * ACCESS: Check access permission 4466 */ 4467 const ACCESS4_READ = 0x0001; 4468 const ACCESS4_LOOKUP = 0x0002; 4469 const ACCESS4_MODIFY = 0x0004; 4470 const ACCESS4_EXTEND = 0x0008; 4471 const ACCESS4_DELETE = 0x0010; 4472 const ACCESS4_EXECUTE = 0x0020; 4474 struct ACCESS4args { 4475 uint32_t access; 4476 }; 4478 struct ACCESS4resok { 4479 uint32_t access; 4480 }; 4482 union ACCESS4res switch (nfsstat4 status) { 4483 case NFS4_OK: 4484 ACCESS4resok resok; 4485 default: 4486 void; 4487 }; 4489 /* 4490 * COMMIT: Commit cached data on server to stable storage 4491 */ 4492 struct COMMIT4args { 4493 offset4 offset; 4494 count4 count; 4495 }; 4497 struct COMMIT4resok { 4498 writeverf4 verf; 4499 }; 4501 union COMMIT4res switch (nfsstat4 status) { 4502 case NFS4_OK: 4503 COMMIT4resok resok; 4504 default: 4505 void; 4506 }; 4508 /* 4509 * CREATE: Create a file 4510 */ 4512 Draft Protocol Specification NFS version 4 February 1999 4514 enum createmode4 { 4515 UNCHECKED = 0, 4516 GUARDED = 1, 4517 EXCLUSIVE = 2 4518 }; 4520 union createhow4 switch (createmode4 mode) { 4521 case UNCHECKED: 4522 case GUARDED: 4523 fattr4 createattrs; 4524 case EXCLUSIVE: 4525 createverf4 verf; 4526 }; 4528 const ACCESS4_READ = 0x0001; 4529 const ACCESS4_MODIFY = 0x0002; 4530 const ACCESS4_LOOKUP = 0x0004; 4531 const ACCESS4_EXTEND = 0x0008; 4532 const ACCESS4_DELETE = 0x0010; 4533 const ACCESS4_EXECUTE = 0x0020; 4535 const DENY4_NONE = 0x0000; 4536 const DENY4_READ = 0x0001; 4537 const DENY4_WRITE = 0x0002; 4539 union openflag switch (uint32_t flag) { 4540 case CREATE: 4541 createhow4 how; 4542 default: 4543 void; 4544 }; 4546 /* 4547 * LOCK/LOCKT/LOCKU: Record lock management 4548 */ 4549 struct LOCK4args { 4550 lock_type type; 4551 seqid4 seqid; 4552 bool reclaim; 4553 nfs_lockowner owner; 4554 offset4 offset; 4555 length4 length; 4556 }; 4558 struct lockres { 4559 stateid4 stateid; 4560 int32_t access; 4561 }; 4563 Draft Protocol Specification NFS version 4 February 1999 4565 union LOCK4res switch (nfsstat4 status) { 4566 case NFS4_OK: 4567 lockres result; 4568 default: 4569 void; 4570 }; 4572 union LOCKT4res switch (nfsstat4 status) { 4573 case NFS4ERR_DENIED: 4574 nfs_lockowner owner; 4575 case NFS4_OK: 4576 void; 4577 default: 4578 void; 4579 }; 4581 union LOCKU4res switch (nfsstat4 status) { 4582 case NFS4_OK: 4583 stateid4 stateid; 4584 default: 4585 stateid4 stateid; 4586 }; 4588 /* 4589 * SETCLIENTID 4590 */ 4591 struct SETCLIENTID4args { 4592 seqid4 seqid; 4593 nfs_client_id client; 4594 }; 4596 union SETCLIENTID4res switch (nfsstat4 status) { 4597 case NFS4_OK: 4598 clientid4 clientid; 4599 default: 4600 void; 4601 }; 4603 /* 4604 * OPEN: Open a file, potentially with a share lock 4605 */ 4606 struct OPEN4args { 4607 filename4 filenames<>; 4608 openflag flag; 4609 nfs_lockowner owner; 4610 seqid4 seqid; 4611 bool reclaim; 4612 int32_t access; 4614 Draft Protocol Specification NFS version 4 February 1999 4616 int32_t deny; 4617 }; 4619 union OPEN4res switch (nfsstat4 status) { 4620 case NFS4_OK: 4621 LOCK4resok resok; 4622 default: 4623 void; 4624 }; 4626 /* 4627 * CLOSE: Close a file and release share locks 4628 */ 4629 struct CLOSE4args { 4630 stateid4 stateid; 4631 }; 4633 union CLOSE4res switch (nfsstat4 status) { 4634 case NFS4_OK: 4635 stateid4 stateid; 4636 default: 4637 void; 4638 }; 4640 /* 4641 * GETATTR: Get file attributes 4642 */ 4643 struct GETATTR4args { 4644 bitmap4 attr_request; 4645 }; 4647 struct GETATTR4resok { 4648 fattr4 obj_attributes; 4649 }; 4651 union GETATTR4res switch (nfsstat4 status) { 4652 case NFS4_OK: 4653 GETATTR4resok resok; 4654 default: 4655 void; 4656 }; 4658 /* 4659 * GETFH: Get current filehandle 4660 */ 4661 struct GETFH4resok { 4662 nfs_fh4 object; 4663 }; 4665 Draft Protocol Specification NFS version 4 February 1999 4667 union GETFH4res switch (nfsstat4 status) { 4668 case NFS4_OK: 4669 GETFH4resok resok; 4670 default: 4671 void; 4672 }; 4674 /* 4675 * LINK: Create link to an object 4676 */ 4677 struct LINK4args { 4678 nfs_fh4 dir; 4679 filename4 newname; 4680 }; 4682 union LINK4res switch (nfsstat4 status) { 4683 case NFS4_OK: 4684 void; 4685 default: 4686 void; 4687 }; 4689 /* 4690 * LOOKUP: Lookup filename 4691 */ 4692 struct LOOKUP4args { 4693 filename4 filenames<>; 4694 }; 4696 union LOOKUP4res switch (nfsstat4 status) { 4697 case NFS4_OK: 4698 void; 4699 default: 4700 void; 4701 }; 4703 /* 4704 * LOOKUPP: Lookup parent directory 4705 */ 4706 union LOOKUPP4res switch (nfsstat4 status) { 4707 case NFS4_OK: 4708 void; 4709 default: 4710 void; 4711 }; 4713 /* 4714 * NVERIFY: Verify attributes different 4716 Draft Protocol Specification NFS version 4 February 1999 4718 */ 4719 struct NVERIFY4args { 4720 bitmap4 attr_request; 4721 fattr4 obj_attributes; 4722 }; 4724 union NVERIFY4res switch (nfsstat4 status) { 4725 case NFS4_OK: 4726 void; 4727 default: 4728 void; 4729 }; 4731 /* 4732 * RESTOREFH: Restore saved filehandle 4733 */ 4735 union RESTOREFH4res switch (nfsstat4 status) { 4736 case NFS4_OK: 4737 void; 4738 default: 4739 void; 4740 }; 4742 /* 4743 * SAVEFH: Save current filehandle 4744 */ 4745 union SAVEFH4res switch (nfsstat4 status) { 4746 case NFS4_OK: 4747 void; 4748 default: 4749 void; 4750 }; 4752 /* 4753 * PUTFH: Set current filehandle 4754 */ 4755 struct PUTFH4args { 4756 nfs_fh4 object; 4757 }; 4759 union PUTFH4res switch (nfsstat4 status) { 4760 case NFS4_OK: 4761 void; 4762 default: 4763 void; 4764 }; 4766 Draft Protocol Specification NFS version 4 February 1999 4768 /* 4769 * PUTROOTFH: Set root filehandle 4770 */ 4771 union PUTROOTFH4res switch (nfsstat4 status) { 4772 case NFS4_OK: 4773 void; 4774 default: 4775 void; 4776 }; 4778 /* 4779 * READ: Read from file 4780 */ 4781 struct READ4args { 4782 stateid4 stateid; 4783 offset4 offset; 4784 count4 count; 4785 }; 4787 struct READ4resok { 4788 bool eof; 4789 opaque data<>; 4790 }; 4792 union READ4res switch (nfsstat4 status) { 4793 case NFS4_OK: 4794 READ4resok resok; 4795 default: 4796 void; 4797 }; 4799 /* 4800 * READDIR: Read directory 4801 */ 4802 struct READDIR4args { 4803 nfs_cookie4 cookie; 4804 count4 dircount; 4805 count4 maxcount; 4806 bitmap4 attr_request; 4808 }; 4810 struct entry4 { 4811 cookie4 cookie; 4812 filename4 name; 4813 fattr4 attrs; 4814 entry4 *nextentry; 4815 }; 4817 Draft Protocol Specification NFS version 4 February 1999 4819 struct dirlist4 { 4820 entry4 *entries; 4821 bool eof; 4822 }; 4824 struct READDIR4resok { 4825 dirlist4 reply; 4826 }; 4828 union READDIR4res switch (nfsstat4 status) { 4829 case NFS4_OK: 4830 READDIR4resok resok; 4831 default: 4832 void; 4833 }; 4835 /* 4836 * READLINK: Read symbolic link 4837 */ 4838 struct READLINK4resok { 4839 linktext4 link; 4840 }; 4842 union READLINK4res switch (nfsstat4 status) { 4843 case NFS4_OK: 4844 READLINK4resok resok; 4845 default: 4846 void; 4847 }; 4849 /* 4850 * REMOVE: Remove filesystem object 4851 */ 4852 struct REMOVE4args { 4853 filename4 target; 4854 }; 4856 union REMOVE4res switch (nfsstat4 status) { 4857 case NFS4_OK: 4858 void; 4859 default: 4860 void; 4861 }; 4863 /* 4864 * RENAME: Rename directory entry 4866 Draft Protocol Specification NFS version 4 February 1999 4868 */ 4869 struct RENAME4args { 4870 filename4 oldname; 4871 nfs_fh4 newdir; 4872 filename4 newname; 4873 }; 4875 union RENAME4res switch (nfsstat4 status) { 4876 case NFS4_OK: 4877 void; 4878 default: 4879 void; 4880 }; 4882 struct RENEW4args { 4883 stateid4 stateid; 4884 }; 4886 union RENEW4res switch (nfsstat4 status) { 4887 case NFS4_OK: 4888 void; 4889 default: 4890 void; 4891 }; 4893 /* 4894 * SETATTR: Set attributes 4895 */ 4896 struct SETATTR4args { 4897 fattr4 obj_attributes; 4898 }; 4900 union SETATTR4res switch (nfsstat4 status) { 4901 case NFS4_OK: 4902 void; 4903 default: 4904 void; 4905 }; 4907 /* 4908 * VERIFY: Verify attributes same 4909 */ 4910 struct VERIFY4args { 4911 bitmap4 attr_request; 4912 fattr4 obj_attributes; 4913 }; 4915 union VERIFY4res switch (nfsstat4 status) { 4917 Draft Protocol Specification NFS version 4 February 1999 4919 case NFS4_OK: 4920 void; 4921 default: 4922 void; 4923 }; 4925 /* 4926 * WRITE: Write to file 4927 */ 4928 enum stable_how4 { 4929 UNSTABLE = 0, 4930 DATA_SYNC = 1, 4931 FILE_SYNC = 2 4932 }; 4934 struct WRITE4args { 4935 stateid4 stateid; 4936 offset4 offset; 4937 count4 count; 4938 stable_how4 stable; 4939 opaque data<>; 4940 }; 4942 struct WRITE4resok { 4943 count4 count; 4944 stable_how4 committed; 4945 writeverf4 verf; 4946 }; 4948 union WRITE4res switch (nfsstat4 status) { 4949 case NFS4_OK: 4950 WRITE4resok resok; 4951 default: 4952 void; 4953 }; 4955 /* 4956 * SECINFO: Obtain Available Security Mechanisms 4957 */ 4958 struct SECINFO4args { 4959 filename4 name; 4960 }; 4962 struct rpc_flavor_info { 4963 secoid4 oid; 4964 qop4 qop; 4965 rpc_gss_svc_t service; 4966 }; 4968 Draft Protocol Specification NFS version 4 February 1999 4970 struct secinfo4 { 4971 rpc_flavor4 flavor; 4972 rpc_flavor_info *flavor_info; 4973 secinfo4 *nextentry; 4974 }; 4976 struct SECINFO4resok { 4977 secinfo4 reply; 4978 }; 4980 union SECINFO4res switch (nfsstat4 status) { 4981 case NFS4_OK: 4982 SECINFO4resok resok; 4983 default: 4984 void; 4985 }; 4987 enum opcode { 4988 OP_NULL = 0, 4989 OP_ACCESS = 1, 4990 OP_CLOSE = 2, 4991 OP_COMMIT = 3, 4992 OP_GETATTR = 4, 4993 OP_GETFH = 5, 4994 OP_LINK = 6, 4995 OP_LOCK = 7, 4996 OP_LOCKT = 8, 4997 OP_LOCKU = 9, 4998 OP_LOOKUP = 10, 4999 OP_LOOKUPP = 11, 5000 OP_NVERIFY = 12, 5001 OP_OPEN = 13, 5002 OP_PUTFH = 14, 5003 OP_PUTROOTFH = 15, 5004 OP_READ = 16, 5005 OP_READDIR = 17, 5006 OP_READLINK = 18, 5007 OP_REMOVE = 19, 5008 OP_RENAME = 20, 5009 OP_RENEW = 21, 5010 OP_RESTOREFH = 22, 5011 OP_SAVEFH = 23, 5012 OP_SECINFO = 24, 5013 OP_SETATTR = 25, 5014 OP_SETCLIENTID = 26, 5015 OP_VERIFY = 27, 5016 OP_WRITE = 28 5018 Draft Protocol Specification NFS version 4 February 1999 5020 }; 5022 union opunion switch (unsigned opcode) { 5023 case OP_NULL: void; 5024 case OP_ACCESS: ACCESS4args opaccess; 5025 case OP_CLOSE: CLOSE4args opclose; 5026 case OP_COMMIT: COMMIT4args opcommit; 5027 case OP_GETATTR: GETATTR4args opgettattr; 5028 case OP_GETFH: void; 5029 case OP_LINK: LINK4args oplink; 5030 case OP_LOCK: LOCK4args oplock; 5031 case OP_LOCKT: LOCK4args oplockt; 5032 case OP_LOCKU: LOCK4args oplocku; 5033 case OP_LOOKUP: LOOKUP4args oplookup; 5034 case OP_LOOKUPP: void; 5035 case OP_NVERIFY: NVERIFY4args opnverify; 5036 case OP_OPEN: OPEN4args opopen; 5037 case OP_PUTFH: PUTFH4args opputfh; 5038 case OP_PUTROOTFH: void; 5039 case OP_READ: READ4args opread; 5040 case OP_READDIR: READDIR4args opreaddir; 5041 case OP_READLINK: void; 5042 case OP_REMOVE: REMOVE4args opremove; 5043 case OP_RENAME: RENAME4args oprename; 5044 case OP_RENEW: RENEW4args oprenew; 5045 case OP_RESTOREFH: void; 5046 case OP_SAVEFH: void; 5047 case OP_SECINFO: SECINFO4args opsecinfo; 5048 case OP_SETATTR: SETATTR4args opsetattr; 5049 case OP_SETCLIENTID: SETCLIENTID4args opsetclientid; 5050 case OP_VERIFY: VERIFY4args opverify; 5051 case OP_WRITE: WRITE4args opwrite; 5052 }; 5054 struct op { 5055 opunion ops; 5056 }; 5058 union resultdata switch (unsigned resop){ 5059 case OP_NULL: void; 5060 case OP_ACCESS: ACCESS4res op; 5061 case OP_CLOSE: CLOSE4res opclose; 5062 case OP_COMMIT: COMMIT4res opcommit; 5063 case OP_GETATTR: GETATTR4res opgetattr; 5064 case OP_GETFH: GETFH4res opgetfh; 5065 case OP_LINK: LINK4res oplink; 5066 case OP_LOCK: LOCK4res oplock; 5067 case OP_LOCKT: LOCKT4res oplockt; 5069 Draft Protocol Specification NFS version 4 February 1999 5071 case OP_LOCKU: LOCKU4res oplocku; 5072 case OP_LOOKUP: LOOKUP4res oplookup; 5073 case OP_LOOKUPP: LOOKUPP4res oplookupp; 5074 case OP_NVERIFY: NVERIFY4res opnverify; 5075 case OP_OPEN: OPEN4res opopen; 5076 case OP_PUTFH: PUTFH4res opputfh; 5077 case OP_PUTROOTFH: PUTROOTFH4res opputrootfh; 5078 case OP_READ: READ4res opread; 5079 case OP_READDIR: READDIR4res opreaddir; 5080 case OP_READLINK: READLINK4res opreadlink; 5081 case OP_REMOVE: REMOVE4res opremove; 5082 case OP_RENAME: RENAME4res oprename; 5083 case OP_RENEW: RENEW4res oprenew; 5084 case OP_RESTOREFH: RESTOREFH4res oprestorefh; 5085 case OP_SAVEFH: SAVEFH4res opsavefh; 5086 case OP_SECINFO: SECINFO4res opsecinfo; 5087 case OP_SETATTR: SETATTR4res opsetattr; 5088 case OP_SETCLIENTID: SETCLIENTID4res opsetclientid; 5089 case OP_VERIFY: VERIFY4res opverify; 5090 case OP_WRITE: WRITE4res opwrite; 5091 }; 5093 struct COMPOUND4args { 5094 utf8string tag; 5095 op oplist<>; 5096 }; 5098 struct COMPOUND4resok { 5099 utf8string tag; 5100 resultdata data<>; 5101 }; 5103 union COMPOUND4res switch (nfsstat4 status){ 5104 case NFS4_OK: 5105 COMPOUND4resok resok; 5106 default: 5107 void; 5108 }; 5110 /* 5111 * Remote file service routines 5112 */ 5113 program NFS4_PROGRAM { 5114 version NFS_V4 { 5115 void 5116 NFSPROC4_NULL(void) = 0; 5118 Draft Protocol Specification NFS version 4 February 1999 5120 COMPOUND4res 5121 NFSPROC4_COMPOUND(COMPOUND4args) = 1; 5123 } = 4; 5124 } = 100003; 5126 Draft Protocol Specification NFS version 4 February 1999 5128 16. Bibliography 5130 [Gray] 5131 C. Gray, D. Cheriton, "Leases: An Efficient Fault-Tolerant Mechanism 5132 for Distributed File Cache Consistency," Proceedings of the Twelfth 5133 Symposium on Operating Systems Principles, p. 202-210, December 1989. 5135 [Juszczak] 5136 Juszczak, Chet, "Improving the Performance and Correctness of an NFS 5137 Server," USENIX Conference Proceedings, USENIX Association, Berkeley, 5138 CA, June 1990, pages 53-63. Describes reply cache implementation 5139 that avoids work in the server by handling duplicate requests. More 5140 important, though listed as a side-effect, the reply cache aids in 5141 the avoidance of destructive non-idempotent operation re-application 5142 -- improving correctness. 5144 [Kazar] 5145 Kazar, Michael Leon, "Synchronization and Caching Issues in the 5146 Andrew File System," USENIX Conference Proceedings, USENIX 5147 Association, Berkeley, CA, Dallas Winter 1988, pages 27-36. A 5148 description of the cache consistency scheme in AFS. Contrasted with 5149 other distributed file systems. 5151 [Macklem] 5152 Macklem, Rick, "Lessons Learned Tuning the 4.3BSD Reno Implementation 5153 of the NFS Protocol," Winter USENIX Conference Proceedings, USENIX 5154 Association, Berkeley, CA, January 1991. Describes performance work 5155 in tuning the 4.3BSD Reno NFS implementation. Describes performance 5156 improvement (reduced CPU loading) through elimination of data copies. 5158 [Mogul] 5159 Mogul, Jeffrey C., "A Recovery Protocol for Spritely NFS," USENIX 5160 File System Workshop Proceedings, Ann Arbor, MI, USENIX Association, 5161 Berkeley, CA, May 1992. Second paper on Spritely NFS proposes a 5162 lease-based scheme for recovering state of consistency protocol. 5164 [Nowicki] 5165 Nowicki, Bill, "Transport Issues in the Network File System," ACM 5166 SIGCOMM newsletter Computer Communication Review, April 1989. A 5167 brief description of the basis for the dynamic retransmission work. 5169 Draft Protocol Specification NFS version 4 February 1999 5171 [Pawlowski] 5172 Pawlowski, Brian, Ron Hixon, Mark Stein, Joseph Tumminaro, "Network 5173 Computing in the UNIX and IBM Mainframe Environment," Uniforum `89 5174 Conf. Proc., (1989) Description of an NFS server implementation for 5175 IBM's MVS operating system. 5177 [RFC1094] 5178 Sun Microsystems, Inc., "NFS: Network File System Protocol 5179 Specification", RFC1094, March 1989. 5181 http://www.ietf.org/rfc/rfc1094.txt 5183 [RFC1345] 5184 Simonsen, K., "Character Mnemonics & Character Sets", RFC1345, 5185 Rationel Almen Planlaegning, June 1992. 5187 http://www.ietf.org/rfc/rfc1345.txt 5189 [RFC1813] 5190 Callaghan, B., Pawlowski, B., Staubach, P., "NFS Version 3 Protocol 5191 Specification", RFC1813, Sun Microsystems, Inc., June 1995. 5193 http://www.ietf.org/rfc/rfc1813.txt 5195 [RFC1831] 5196 Srinivasan, R., "RPC: Remote Procedure Call Protocol Specification 5197 Version 2", RFC1831, Sun Microsystems, Inc., August 1995. 5199 http://www.ietf.org/rfc/rfc1831.txt 5201 [RFC1832] 5202 Srinivasan, R., "XDR: External Data Representation Standard", 5203 RFC1832, Sun Microsystems, Inc., August 1995. 5205 http://www.ietf.org/rfc/rfc1832.txt 5207 [RFC1833] 5208 Srinivasan, R., "Binding Protocols for ONC RPC Version 2", RFC1833, 5209 Sun Microsystems, Inc., August 1995. 5211 http://www.ietf.org/rfc/rfc1833.txt 5213 Draft Protocol Specification NFS version 4 February 1999 5215 [RFC2054] 5216 Callaghan, B., "WebNFS Client Specification", RFC2054, Sun 5217 Microsystems, Inc., October 1996 5219 http://www.ietf.org/rfc/rfc2054.txt 5221 [RFC2055] 5222 Callaghan, B., "WebNFS Server Specification", RFC2054, Sun 5223 Microsystems, Inc., October 1996 5225 http://www.ietf.org/rfc/rfc2055.txt 5227 [RFC2078] 5228 Linn, J., "Generic Security Service Application Program Interface, 5229 Version 2", RFC2078, OpenVision Technologies, January 1997. 5231 http://www.ietf.org/rfc/rfc2078.txt 5233 [RFC2152] 5234 Goldsmith, D., "UTF-7 A Mail-Safe Transformation Format of Unicode", 5235 RFC2152, Apple Computer, Inc., May 1997 5237 http://www.ietf.org/rfc/rfc2152.txt 5239 [RFC2203] 5240 Eisler, M., Chiu, A., Ling, L., "RPCSEC_GSS Protocol Specification", 5241 RFC2203, Sun Microsystems, Inc., August 1995. 5243 http://www.ietf.org/rfc/rfc2203.txt 5245 [RFC2279] 5246 Yergeau, F., "UTF-8, a transformation format of ISO 10646", RFC2279, 5247 Alis Technologies, January 1998. 5249 http://www.ietf.org/rfc/rfc2279.txt 5251 [Sandberg] 5252 Sandberg, R., D. Goldberg, S. Kleiman, D. Walsh, B. Lyon, "Design 5253 and Implementation of the Sun Network Filesystem," USENIX Conference 5254 Proceedings, USENIX Association, Berkeley, CA, Summer 1985. The 5255 basic paper describing the SunOS implementation of the NFS version 2 5256 protocol, and discusses the goals, protocol specification and trade- 5258 Draft Protocol Specification NFS version 4 February 1999 5260 offs. 5262 [SPNEGO] 5263 Baize, E., Pinkas, D., "The Simple and Protected GSS-API Negotiation 5264 Mechanism", draft-ietf-cat-snego-09.txt, Bull, April 1998. 5266 ftp://ftp.isi.edu/internet-drafts/draft-ietf-cat-snego-09.txt 5268 [Srinivasan] 5269 Srinivasan, V., Jeffrey C. Mogul, "Spritely NFS: Implementation and 5270 Performance of Cache Consistency Protocols", WRL Research Report 5271 89/5, Digital Equipment Corporation Western Research Laboratory, 100 5272 Hamilton Ave., Palo Alto, CA, 94301, May 1989. This paper analyzes 5273 the effect of applying a Sprite-like consistency protocol applied to 5274 standard NFS. The issues of recovery in a stateful environment are 5275 covered in [Mogul]. 5277 [Unicode1] 5278 "Unicode Technical Report #8 - The Unicode Standard, Version 2.1", 5279 Unicode, Inc., The Unicode Consortium, P.O. Box 700519, San Jose, CA 5280 95710-0519 USA, September 1998 5282 http://www.unicode.org/unicode/reports/tr8.html 5284 [Unicode2] 5285 "Unsupported Scripts" Unicode, Inc., The Unicode Consortium, P.O. Box 5286 700519, San Jose, CA 95710-0519 USA, October 1998 5288 http://www.unicode.org/unicode/standard/unsupported.html 5290 [XNFS] 5291 The Open Group, Protocols for Interworking: XNFS, Version 3W, The 5292 Open Group, 1010 El Camino Real Suite 380, Menlo Park, CA 94025, ISBN 5293 1-85912-184-5, February 1998. 5295 HTML version available: http://www.opengroup.org 5297 Draft Protocol Specification NFS version 4 February 1999 5299 17. Authors and Contributors 5301 General feedback related to this document should be directed to: 5303 nfsv4-wg@sunroof.eng.sun.com 5305 or the editor. 5307 17.1. Contributors 5309 The following individuals have contributed to the document: 5311 Carl Beame, beame@bws.com, of Hummingbird Communications Ltd. 5313 17.2. Editor's Address 5315 Spencer Shepler 5316 Sun Microsystems, Inc. 5317 7808 Moonflower Drive 5318 Austin, Texas 78750 5320 Phone: +1 512-349-9376 5321 E-mail: shepler@eng.sun.com 5323 17.3. Authors' Addresses 5325 Brent Callaghan 5326 Sun Microsystems, Inc. 5327 901 San Antonio Road 5328 Palo Alto, CA 94303 5330 Phone: +1 650-786-5067 5331 E-mail: brent.callaghan@eng.sun.com 5333 Mike Eisler 5334 Sun Microsystems, Inc. 5335 5565 Wilson Road 5336 Colorado Springs, CO 80919 5338 Phone: +1 719-599-9026 5339 E-mail: mre@eng.sun.com 5341 David Robinson 5342 Sun Microsystems, Inc. 5343 901 San Antonio Road 5344 Palo Alto, CA 94303 5346 Draft Protocol Specification NFS version 4 February 1999 5348 Phone: +1 650-786-5088 5349 E-mail: david.robinson@eng.sun.com 5351 Robert Thurlow 5352 Sun Microsystems, Inc. 5353 901 San Antonio Road 5354 Palo Alto, CA 94303 5356 Phone: +1 650-786-5096 5357 E-mail: robert.thurlow@eng.sun.com 5359 Draft Protocol Specification NFS version 4 February 1999 5361 18. Full Copyright Statement 5363 "Copyright (C) The Internet Society (1999). All Rights Reserved. 5365 This document and translations of it may be copied and furnished to 5366 others, and derivative works that comment on or otherwise explain it 5367 or assist in its implmentation may be prepared, copied, published and 5368 distributed, in whole or in part, without restriction of any kind, 5369 provided that the above copyright notice and this paragraph are 5370 included on all such copies and derivative works. However, this 5371 document itself may not be modified in any way, such as by removing 5372 the copyright notice or references to the Internet Society or other 5373 Internet organizations, except as needed for the purpose of 5374 developing Internet standards in which case the procedures for 5375 copyrights defined in the Internet Standards process must be 5376 followed, or as required to translate it into languages other than 5377 English. 5379 The limited permissions granted above are perpetual and will not be 5380 revoked by the Internet Society or its successors or assigns. 5382 This document and the information contained herein is provided on an 5383 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 5384 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 5385 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 5386 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 5387 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE."