| draft-ietf-nfsv4-rfc3530bis-35.txt | | rfc7530.txt | |
| | | | |
|
| NFSv4 T. Haynes, Ed. | | Internet Engineering Task Force (IETF) T. Haynes, Ed. | |
| Internet-Draft Primary Data | | Request for Comments: 7530 Primary Data | |
| Obsoletes: 3530 (if approved) D. Noveck, Ed. | | Obsoletes: 3530 D. Noveck, Ed. | |
| Intended status: Standards Track Dell | | Category: Standards Track Dell | |
| Expires: June 7, 2015 December 04, 2014 | | ISSN: 2070-1721 March 2015 | |
| | | | |
| Network File System (NFS) Version 4 Protocol | | Network File System (NFS) Version 4 Protocol | |
|
| draft-ietf-nfsv4-rfc3530bis-35.txt | | | |
| | | | |
| Abstract | | Abstract | |
| | | | |
|
| The Network File System (NFS) version 4 is a distributed file system | | The Network File System (NFS) version 4 protocol is a distributed | |
| protocol which builds on the heritage of NFS protocol version 2, RFC | | file system protocol that builds on the heritage of NFS protocol | |
| 1094, and version 3, RFC 1813. Unlike earlier versions, the NFS | | version 2 (RFC 1094) and version 3 (RFC 1813). Unlike earlier | |
| version 4 protocol supports traditional file access while integrating | | versions, the NFS version 4 protocol supports traditional file access | |
| support for file locking and the mount protocol. In addition, | | while integrating support for file locking and the MOUNT protocol. | |
| support for strong security (and its negotiation), compound | | In addition, support for strong security (and its negotiation), | |
| operations, client caching, and internationalization have been added. | | COMPOUND operations, client caching, and internationalization has | |
| Of course, attention has been applied to making NFS version 4 operate | | been added. Of course, attention has been applied to making NFS | |
| well in an Internet environment. | | version 4 operate well in an Internet environment. | |
| | | | |
| This document, together with the companion XDR description document, | | | |
| RFCNFSv4XDR, obsoletes RFC 3530 as the definition of the NFS version | | | |
| 4 protocol. | | | |
| | | | |
| Requirements Language | | | |
| | | | |
|
| The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", | | This document, together with the companion External Data | |
| "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this | | Representation (XDR) description document, RFC 7531, obsoletes RFC | |
| document are to be interpreted as described in RFC 2119 [RFC2119] | | 3530 as the definition of the NFS version 4 protocol. | |
| except where "REQUIRED" and "RECOMMENDED" are used as qualifiers to | | | |
| distinguish classes of attributes as described in Section 1.3.3.2 and | | | |
| Section 5. | | | |
| | | | |
| Status of This Memo | | Status of This Memo | |
| | | | |
|
| This Internet-Draft is submitted in full conformance with the | | This is an Internet Standards Track document. | |
| provisions of BCP 78 and BCP 79. | | | |
| | | | |
| Internet-Drafts are working documents of the Internet Engineering | | | |
| Task Force (IETF). Note that other groups may also distribute | | | |
| working documents as Internet-Drafts. The list of current Internet- | | | |
| Drafts is at http://datatracker.ietf.org/drafts/current/. | | | |
| | | | |
|
| Internet-Drafts are draft documents valid for a maximum of six months | | This document is a product of the Internet Engineering Task Force | |
| and may be updated, replaced, or obsoleted by other documents at any | | (IETF). It represents the consensus of the IETF community. It has | |
| time. It is inappropriate to use Internet-Drafts as reference | | received public review and has been approved for publication by the | |
| material or to cite them other than as "work in progress." | | Internet Engineering Steering Group (IESG). Further information on | |
| | | Internet Standards is available in Section 2 of RFC 5741. | |
| | | | |
|
| This Internet-Draft will expire on June 7, 2015. | | Information about the current status of this document, any errata, | |
| | | and how to provide feedback on it may be obtained at | |
| | | http://www.rfc-editor.org/info/rfc7530. | |
| | | | |
| Copyright Notice | | Copyright Notice | |
| | | | |
|
| Copyright (c) 2014 IETF Trust and the persons identified as the | | Copyright (c) 2015 IETF Trust and the persons identified as the | |
| document authors. All rights reserved. | | document authors. All rights reserved. | |
| | | | |
| This document is subject to BCP 78 and the IETF Trust's Legal | | This document is subject to BCP 78 and the IETF Trust's Legal | |
| Provisions Relating to IETF Documents | | Provisions Relating to IETF Documents | |
| (http://trustee.ietf.org/license-info) in effect on the date of | | (http://trustee.ietf.org/license-info) in effect on the date of | |
| publication of this document. Please review these documents | | publication of this document. Please review these documents | |
| carefully, as they describe your rights and restrictions with respect | | carefully, as they describe your rights and restrictions with respect | |
| to this document. Code Components extracted from this document must | | to this document. Code Components extracted from this document must | |
| include Simplified BSD License text as described in Section 4.e of | | include Simplified BSD License text as described in Section 4.e of | |
| the Trust Legal Provisions and are provided without warranty as | | the Trust Legal Provisions and are provided without warranty as | |
| | | | |
| skipping to change at page 2, line 38 | | skipping to change at page 2, line 34 | |
| modifications of such material outside the IETF Standards Process. | | modifications of such material outside the IETF Standards Process. | |
| Without obtaining an adequate license from the person(s) controlling | | Without obtaining an adequate license from the person(s) controlling | |
| the copyright in such materials, this document may not be modified | | the copyright in such materials, this document may not be modified | |
| outside the IETF Standards Process, and derivative works of it may | | outside the IETF Standards Process, and derivative works of it may | |
| not be created outside the IETF Standards Process, except to format | | not be created outside the IETF Standards Process, except to format | |
| it for publication as an RFC or to translate it into languages other | | it for publication as an RFC or to translate it into languages other | |
| than English. | | than English. | |
| | | | |
| Table of Contents | | Table of Contents | |
| | | | |
|
| 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 7 | | 1. Introduction ....................................................8 | |
| 1.1. NFS Version 4 Goals . . . . . . . . . . . . . . . . . . . 7 | | 1.1. Requirements Language ......................................8 | |
| 1.2. Definitions in the companion document NFS Version 4 | | 1.2. NFS Version 4 Goals ........................................8 | |
| Protocol are Authoritative . . . . . . . . . . . . . . . 8 | | 1.3. Definitions in the Companion Document RFC 7531 Are | |
| 1.3. Overview of NFSv4 Features . . . . . . . . . . . . . . . 8 | | Authoritative ..............................................9 | |
| 1.3.1. RPC and Security . . . . . . . . . . . . . . . . . . 9 | | 1.4. Overview of NFSv4 Features .................................9 | |
| 1.3.2. Procedure and Operation Structure . . . . . . . . . . 9 | | 1.4.1. RPC and Security ....................................9 | |
| 1.3.3. Filesystem Model . . . . . . . . . . . . . . . . . . 10 | | 1.4.2. Procedure and Operation Structure ..................10 | |
| 1.3.4. OPEN and CLOSE . . . . . . . . . . . . . . . . . . . 12 | | 1.4.3. File System Model ..................................10 | |
| 1.3.5. File Locking . . . . . . . . . . . . . . . . . . . . 12 | | 1.4.4. OPEN and CLOSE .....................................12 | |
| 1.3.6. Client Caching and Delegation . . . . . . . . . . . . 12 | | 1.4.5. File Locking .......................................12 | |
| 1.4. General Definitions . . . . . . . . . . . . . . . . . . . 13 | | 1.4.6. Client Caching and Delegation ......................13 | |
| 1.5. Changes since RFC 3530 . . . . . . . . . . . . . . . . . 15 | | 1.5. General Definitions .......................................14 | |
| 1.6. Changes between RFC 3010 and RFC3530 . . . . . . . . . . 16 | | 1.6. Changes since RFC 3530 ....................................16 | |
| | | 1.7. Changes between RFC 3010 and RFC 3530 .....................16 | |
| | | 2. Protocol Data Types ............................................18 | |
| | | 2.1. Basic Data Types ..........................................18 | |
| | | 2.2. Structured Data Types .....................................21 | |
| | | | |
|
| 2. Protocol Data Types . . . . . . . . . . . . . . . . . . . . . 17 | | 3. RPC and Security Flavor ........................................25 | |
| 2.1. Basic Data Types . . . . . . . . . . . . . . . . . . . . 17 | | 3.1. Ports and Transports ......................................25 | |
| 2.2. Structured Data Types . . . . . . . . . . . . . . . . . . 19 | | 3.1.1. Client Retransmission Behavior .....................26 | |
| 3. RPC and Security Flavor . . . . . . . . . . . . . . . . . . . 23 | | 3.2. Security Flavors ..........................................27 | |
| 3.1. Ports and Transports . . . . . . . . . . . . . . . . . . 23 | | 3.2.1. Security Mechanisms for NFSv4 ......................27 | |
| 3.1.1. Client Retransmission Behavior . . . . . . . . . . . 24 | | 3.3. Security Negotiation ......................................28 | |
| 3.2. Security Flavors . . . . . . . . . . . . . . . . . . . . 25 | | 3.3.1. SECINFO ............................................29 | |
| 3.2.1. Security mechanisms for NFSv4 . . . . . . . . . . . . 25 | | 3.3.2. Security Error .....................................29 | |
| 3.3. Security Negotiation . . . . . . . . . . . . . . . . . . 26 | | 3.3.3. Callback RPC Authentication ........................29 | |
| 3.3.1. SECINFO . . . . . . . . . . . . . . . . . . . . . . . 27 | | 4. Filehandles ....................................................30 | |
| 3.3.2. Security Error . . . . . . . . . . . . . . . . . . . 27 | | 4.1. Obtaining the First Filehandle ............................30 | |
| 3.3.3. Callback RPC Authentication . . . . . . . . . . . . . 27 | | 4.1.1. Root Filehandle ....................................31 | |
| 4. Filehandles . . . . . . . . . . . . . . . . . . . . . . . . . 28 | | 4.1.2. Public Filehandle ..................................31 | |
| 4.1. Obtaining the First Filehandle . . . . . . . . . . . . . 28 | | 4.2. Filehandle Types ..........................................31 | |
| 4.1.1. Root Filehandle . . . . . . . . . . . . . . . . . . . 29 | | 4.2.1. General Properties of a Filehandle .................32 | |
| 4.1.2. Public Filehandle . . . . . . . . . . . . . . . . . . 29 | | 4.2.2. Persistent Filehandle ..............................32 | |
| 4.2. Filehandle Types . . . . . . . . . . . . . . . . . . . . 29 | | 4.2.3. Volatile Filehandle ................................33 | |
| 4.2.1. General Properties of a Filehandle . . . . . . . . . 30 | | 4.2.4. One Method of Constructing a Volatile Filehandle ...34 | |
| 4.2.2. Persistent Filehandle . . . . . . . . . . . . . . . . 30 | | 4.3. Client Recovery from Filehandle Expiration ................35 | |
| 4.2.3. Volatile Filehandle . . . . . . . . . . . . . . . . . 31 | | 5. Attributes .....................................................35 | |
| 4.2.4. One Method of Constructing a Volatile Filehandle . . 32 | | 5.1. REQUIRED Attributes .......................................37 | |
| 4.3. Client Recovery from Filehandle Expiration . . . . . . . 33 | | 5.2. RECOMMENDED Attributes ....................................37 | |
| 5. Attributes . . . . . . . . . . . . . . . . . . . . . . . . . 33 | | 5.3. Named Attributes ..........................................37 | |
| 5.1. REQUIRED Attributes . . . . . . . . . . . . . . . . . . . 35 | | 5.4. Classification of Attributes ..............................39 | |
| 5.2. RECOMMENDED Attributes . . . . . . . . . . . . . . . . . 35 | | 5.5. Set-Only and Get-Only Attributes ..........................40 | |
| 5.3. Named Attributes . . . . . . . . . . . . . . . . . . . . 35 | | 5.6. REQUIRED Attributes - List and Definition References ......40 | |
| 5.4. Classification of Attributes . . . . . . . . . . . . . . 37 | | 5.7. RECOMMENDED Attributes - List and Definition References ...41 | |
| 5.5. Set-Only and Get-Only Attributes . . . . . . . . . . . . 38 | | 5.8. Attribute Definitions .....................................42 | |
| 5.6. REQUIRED Attributes - List and Definition References . . 38 | | 5.8.1. Definitions of REQUIRED Attributes .................42 | |
| 5.7. RECOMMENDED Attributes - List and Definition References . 39 | | 5.8.2. Definitions of Uncategorized RECOMMENDED | |
| 5.8. Attribute Definitions . . . . . . . . . . . . . . . . . . 41 | | Attributes .........................................45 | |
| 5.8.1. Definitions of REQUIRED Attributes . . . . . . . . . 41 | | 5.9. Interpreting owner and owner_group ........................51 | |
| 5.8.2. Definitions of Uncategorized RECOMMENDED Attributes . 43 | | 5.10. Character Case Attributes ................................53 | |
| 5.9. Interpreting owner and owner_group . . . . . . . . . . . 49 | | 6. Access Control Attributes ......................................54 | |
| 5.10. Character Case Attributes . . . . . . . . . . . . . . . . 52 | | 6.1. Goals .....................................................54 | |
| 6. Access Control Attributes . . . . . . . . . . . . . . . . . . 52 | | 6.2. File Attributes Discussion ................................55 | |
| 6.1. Goals . . . . . . . . . . . . . . . . . . . . . . . . . . 52 | | 6.2.1. Attribute 12: acl ..................................55 | |
| 6.2. File Attributes Discussion . . . . . . . . . . . . . . . 53 | | 6.2.2. Attribute 33: mode .................................70 | |
| 6.2.1. Attribute 12: acl . . . . . . . . . . . . . . . . . . 53 | | 6.3. Common Methods ............................................71 | |
| 6.2.2. Attribute 33: mode . . . . . . . . . . . . . . . . . 68 | | 6.3.1. Interpreting an ACL ................................71 | |
| 6.3. Common Methods . . . . . . . . . . . . . . . . . . . . . 68 | | 6.3.2. Computing a mode Attribute from an ACL .............72 | |
| 6.3.1. Interpreting an ACL . . . . . . . . . . . . . . . . . 68 | | 6.4. Requirements ..............................................73 | |
| 6.3.2. Computing a Mode Attribute from an ACL . . . . . . . 69 | | 6.4.1. Setting the mode and/or ACL Attributes .............74 | |
| 6.4. Requirements . . . . . . . . . . . . . . . . . . . . . . 70 | | 6.4.2. Retrieving the mode and/or ACL Attributes ..........75 | |
| 6.4.1. Setting the mode and/or ACL Attributes . . . . . . . 71 | | 6.4.3. Creating New Objects ...............................75 | |
| 6.4.2. Retrieving the mode and/or ACL Attributes . . . . . . 72 | | | |
| 6.4.3. Creating New Objects . . . . . . . . . . . . . . . . 72 | | 7. NFS Server Namespace ...........................................77 | |
| 7. NFS Server Name Space . . . . . . . . . . . . . . . . . . . . 74 | | 7.1. Server Exports ............................................77 | |
| 7.1. Server Exports . . . . . . . . . . . . . . . . . . . . . 74 | | 7.2. Browsing Exports ..........................................77 | |
| 7.2. Browsing Exports . . . . . . . . . . . . . . . . . . . . 75 | | 7.3. Server Pseudo-File System .................................78 | |
| 7.3. Server Pseudo Filesystem . . . . . . . . . . . . . . . . 75 | | 7.4. Multiple Roots ............................................79 | |
| 7.4. Multiple Roots . . . . . . . . . . . . . . . . . . . . . 76 | | 7.5. Filehandle Volatility .....................................79 | |
| 7.5. Filehandle Volatility . . . . . . . . . . . . . . . . . . 76 | | 7.6. Exported Root .............................................79 | |
| 7.6. Exported Root . . . . . . . . . . . . . . . . . . . . . . 76 | | 7.7. Mount Point Crossing ......................................79 | |
| 7.7. Mount Point Crossing . . . . . . . . . . . . . . . . . . 76 | | 7.8. Security Policy and Namespace Presentation ................80 | |
| 7.8. Security Policy and Name Space Presentation . . . . . . . 77 | | 8. Multi-Server Namespace .........................................81 | |
| 8. Multi-Server Namespace . . . . . . . . . . . . . . . . . . . 78 | | 8.1. Location Attributes .......................................81 | |
| 8.1. Location Attributes . . . . . . . . . . . . . . . . . . . 78 | | 8.2. File System Presence or Absence ...........................81 | |
| 8.2. File System Presence or Absence . . . . . . . . . . . . . 78 | | 8.3. Getting Attributes for an Absent File System ..............83 | |
| 8.3. Getting Attributes for an Absent File System . . . . . . 79 | | 8.3.1. GETATTR within an Absent File System ...............83 | |
| 8.3.1. GETATTR Within an Absent File System . . . . . . . . 80 | | 8.3.2. READDIR and Absent File Systems ....................84 | |
| 8.3.2. READDIR and Absent File Systems . . . . . . . . . . . 81 | | 8.4. Uses of Location Information ..............................84 | |
| 8.4. Uses of Location Information . . . . . . . . . . . . . . 81 | | 8.4.1. File System Replication ............................85 | |
| 8.4.1. File System Replication . . . . . . . . . . . . . . . 82 | | 8.4.2. File System Migration ..............................86 | |
| 8.4.2. File System Migration . . . . . . . . . . . . . . . . 83 | | 8.4.3. Referrals ..........................................86 | |
| 8.4.3. Referrals . . . . . . . . . . . . . . . . . . . . . . 83 | | 8.5. Location Entries and Server Identity ......................87 | |
| 8.5. Location Entries and Server Identity . . . . . . . . . . 84 | | 8.6. Additional Client-Side Considerations .....................88 | |
| 8.6. Additional Client-Side Considerations . . . . . . . . . . 85 | | 8.7. Effecting File System Referrals ...........................89 | |
| 8.7. Effecting File System Referrals . . . . . . . . . . . . . 86 | | 8.7.1. Referral Example (LOOKUP) ..........................89 | |
| 8.7.1. Referral Example (LOOKUP) . . . . . . . . . . . . . . 86 | | 8.7.2. Referral Example (READDIR) .........................93 | |
| 8.7.2. Referral Example (READDIR) . . . . . . . . . . . . . 90 | | 8.8. The Attribute fs_locations ................................96 | |
| 8.8. The Attribute fs_locations . . . . . . . . . . . . . . . 92 | | 9. File Locking and Share Reservations ............................98 | |
| 9. File Locking and Share Reservations . . . . . . . . . . . . . 94 | | 9.1. Opens and Byte-Range Locks ................................99 | |
| 9.1. Opens and Byte-Range Locks . . . . . . . . . . . . . . . 95 | | 9.1.1. Client ID ..........................................99 | |
| 9.1.1. Client ID . . . . . . . . . . . . . . . . . . . . . . 95 | | 9.1.2. Server Release of Client ID .......................102 | |
| 9.1.2. Server Release of Client ID . . . . . . . . . . . . . 98 | | 9.1.3. Use of Seqids .....................................103 | |
| 9.1.3. Use of Seqids . . . . . . . . . . . . . . . . . . . . 99 | | 9.1.4. Stateid Definition ................................104 | |
| 9.1.4. Stateid Definition . . . . . . . . . . . . . . . . . 100 | | 9.1.5. Lock-Owner ........................................110 | |
| 9.1.5. lock-owner . . . . . . . . . . . . . . . . . . . . . 106 | | 9.1.6. Use of the Stateid and Locking ....................110 | |
| 9.1.6. Use of the Stateid and Locking . . . . . . . . . . . 107 | | 9.1.7. Sequencing of Lock Requests .......................113 | |
| 9.1.7. Sequencing of Lock Requests . . . . . . . . . . . . . 109 | | 9.1.8. Recovery from Replayed Requests ...................114 | |
| 9.1.8. Recovery from Replayed Requests . . . . . . . . . . . 110 | | 9.1.9. Interactions of Multiple Sequence Values ..........114 | |
| 9.1.9. Interactions of multiple sequence values . . . . . . 110 | | 9.1.10. Releasing State-Owner State ......................115 | |
| 9.1.10. Releasing state-owner State . . . . . . . . . . . . . 111 | | 9.1.11. Use of Open Confirmation .........................116 | |
| 9.1.11. Use of Open Confirmation . . . . . . . . . . . . . . 112 | | 9.2. Lock Ranges ..............................................117 | |
| 9.2. Lock Ranges . . . . . . . . . . . . . . . . . . . . . . . 113 | | 9.3. Upgrading and Downgrading Locks ..........................117 | |
| 9.3. Upgrading and Downgrading Locks . . . . . . . . . . . . . 113 | | 9.4. Blocking Locks ...........................................118 | |
| 9.4. Blocking Locks . . . . . . . . . . . . . . . . . . . . . 114 | | 9.5. Lease Renewal ............................................119 | |
| 9.5. Lease Renewal . . . . . . . . . . . . . . . . . . . . . . 115 | | 9.6. Crash Recovery ...........................................120 | |
| 9.6. Crash Recovery . . . . . . . . . . . . . . . . . . . . . 116 | | 9.6.1. Client Failure and Recovery .......................120 | |
| 9.6.1. Client Failure and Recovery . . . . . . . . . . . . . 116 | | 9.6.2. Server Failure and Recovery .......................120 | |
| 9.6.2. Server Failure and Recovery . . . . . . . . . . . . . 116 | | 9.6.3. Network Partitions and Recovery ...................122 | |
| 9.6.3. Network Partitions and Recovery . . . . . . . . . . . 118 | | 9.7. Recovery from a Lock Request Timeout or Abort ............130 | |
| 9.7. Recovery from a Lock Request Timeout or Abort . . . . . . 126 | | 9.8. Server Revocation of Locks ...............................130 | |
| 9.8. Server Revocation of Locks . . . . . . . . . . . . . . . 126 | | 9.9. Share Reservations .......................................132 | |
| 9.9. Share Reservations . . . . . . . . . . . . . . . . . . . 128 | | 9.10. OPEN/CLOSE Operations ...................................132 | |
| 9.10. OPEN/CLOSE Operations . . . . . . . . . . . . . . . . . . 128 | | 9.10.1. Close and Retention of State Information .........133 | |
| 9.10.1. Close and Retention of State Information . . . . . . 129 | | 9.11. Open Upgrade and Downgrade ..............................134 | |
| 9.11. Open Upgrade and Downgrade . . . . . . . . . . . . . . . 130 | | 9.12. Short and Long Leases ...................................135 | |
| 9.12. Short and Long Leases . . . . . . . . . . . . . . . . . . 130 | | 9.13. Clocks, Propagation Delay, and Calculating Lease | |
| 9.13. Clocks, Propagation Delay, and Calculating Lease | | Expiration ..............................................135 | |
| Expiration . . . . . . . . . . . . . . . . . . . . . . . 131 | | 9.14. Migration, Replication, and State .......................136 | |
| 9.14. Migration, Replication and State . . . . . . . . . . . . 131 | | 9.14.1. Migration and State ..............................136 | |
| 9.14.1. Migration and State . . . . . . . . . . . . . . . . 132 | | 9.14.2. Replication and State ............................137 | |
| 9.14.2. Replication and State . . . . . . . . . . . . . . . 133 | | 9.14.3. Notification of Migrated Lease ...................137 | |
| 9.14.3. Notification of Migrated Lease . . . . . . . . . . . 133 | | 9.14.4. Migration and the lease_time Attribute ...........138 | |
| 9.14.4. Migration and the lease_time Attribute . . . . . . . 134 | | 10. Client-Side Caching ..........................................139 | |
| 10. Client-Side Caching . . . . . . . . . . . . . . . . . . . . . 135 | | 10.1. Performance Challenges for Client-Side Caching ..........139 | |
| 10.1. Performance Challenges for Client-Side Caching . . . . . 135 | | 10.2. Delegation and Callbacks ................................140 | |
| 10.2. Delegation and Callbacks . . . . . . . . . . . . . . . . 136 | | 10.2.1. Delegation Recovery ..............................142 | |
| 10.2.1. Delegation Recovery . . . . . . . . . . . . . . . . 138 | | 10.3. Data Caching ............................................147 | |
| 10.3. Data Caching . . . . . . . . . . . . . . . . . . . . . . 142 | | 10.3.1. Data Caching and OPENs ...........................147 | |
| 10.3.1. Data Caching and OPENs . . . . . . . . . . . . . . . 143 | | 10.3.2. Data Caching and File Locking ....................148 | |
| 10.3.2. Data Caching and File Locking . . . . . . . . . . . 144 | | 10.3.3. Data Caching and Mandatory File Locking ..........150 | |
| 10.3.3. Data Caching and Mandatory File Locking . . . . . . 145 | | 10.3.4. Data Caching and File Identity ...................150 | |
| 10.3.4. Data Caching and File Identity . . . . . . . . . . . 146 | | 10.4. Open Delegation .........................................151 | |
| 10.4. Open Delegation . . . . . . . . . . . . . . . . . . . . 147 | | 10.4.1. Open Delegation and Data Caching .................154 | |
| 10.4.1. Open Delegation and Data Caching . . . . . . . . . . 149 | | 10.4.2. Open Delegation and File Locks ...................155 | |
| 10.4.2. Open Delegation and File Locks . . . . . . . . . . . 151 | | 10.4.3. Handling of CB_GETATTR ...........................155 | |
| 10.4.3. Handling of CB_GETATTR . . . . . . . . . . . . . . . 151 | | 10.4.4. Recall of Open Delegation ........................158 | |
| 10.4.4. Recall of Open Delegation . . . . . . . . . . . . . 154 | | 10.4.5. OPEN Delegation Race with CB_RECALL ..............160 | |
| 10.4.5. OPEN Delegation Race with CB_RECALL . . . . . . . . 156 | | 10.4.6. Clients That Fail to Honor Delegation Recalls ....161 | |
| 10.4.6. Clients that Fail to Honor Delegation Recalls . . . 157 | | 10.4.7. Delegation Revocation ............................162 | |
| 10.4.7. Delegation Revocation . . . . . . . . . . . . . . . 158 | | 10.5. Data Caching and Revocation .............................162 | |
| 10.5. Data Caching and Revocation . . . . . . . . . . . . . . 158 | | 10.5.1. Revocation Recovery for Write Open Delegation ....163 | |
| 10.5.1. Revocation Recovery for Write Open Delegation . . . 159 | | 10.6. Attribute Caching .......................................164 | |
| 10.6. Attribute Caching . . . . . . . . . . . . . . . . . . . 159 | | 10.7. Data and Metadata Caching and Memory-Mapped Files .......166 | |
| 10.7. Data and Metadata Caching and Memory Mapped Files . . . 161 | | 10.8. Name Caching ............................................168 | |
| 10.8. Name Caching . . . . . . . . . . . . . . . . . . . . . . 163 | | 10.9. Directory Caching .......................................169 | |
| 10.9. Directory Caching . . . . . . . . . . . . . . . . . . . 164 | | 11. Minor Versioning .............................................170 | |
| 11. Minor Versioning . . . . . . . . . . . . . . . . . . . . . . 165 | | 12. Internationalization .........................................170 | |
| 12. Internationalization . . . . . . . . . . . . . . . . . . . . 166 | | 12.1. Introduction ............................................170 | |
| 12.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 166 | | 12.2. Limitations on Internationalization-Related | |
| 12.2. Limitations on internationalization-related processing | | Processing in the NFSv4 Context .........................172 | |
| in the NFSv4 context . . . . . . . . . . . . . . . . . . 168 | | 12.3. Summary of Server Behavior Types ........................173 | |
| 12.3. Summary of Server Behavior Types . . . . . . . . . . . . 168 | | 12.4. String Encoding .........................................173 | |
| 12.4. String Encoding . . . . . . . . . . . . . . . . . . . . 169 | | 12.5. Normalization ...........................................174 | |
| 12.5. Normalization . . . . . . . . . . . . . . . . . . . . . 170 | | 12.6. Types with Processing Defined by Other Internet Areas ...175 | |
| 12.6. Types with Processing Defined by Other Internet Areas . 171 | | 12.7. Errors Related to UTF-8 .................................177 | |
| 12.7. UTF-8 Related Errors . . . . . . . . . . . . . . . . . . 172 | | 12.8. Servers That Accept File Component Names That | |
| 12.8. Servers that accept file component names that are not | | Are Not Valid UTF-8 Strings .............................177 | |
| valid UTF-8 strings . . . . . . . . . . . . . . . . . . 173 | | | |
| 13. Error Values . . . . . . . . . . . . . . . . . . . . . . . . 174 | | 13. Error Values .................................................178 | |
| 13.1. Error Definitions . . . . . . . . . . . . . . . . . . . 174 | | 13.1. Error Definitions .......................................179 | |
| 13.1.1. General Errors . . . . . . . . . . . . . . . . . . . 175 | | 13.1.1. General Errors ...................................180 | |
| 13.1.2. Filehandle Errors . . . . . . . . . . . . . . . . . 177 | | 13.1.2. Filehandle Errors ................................181 | |
| 13.1.3. Compound Structure Errors . . . . . . . . . . . . . 178 | | 13.1.3. Compound Structure Errors ........................183 | |
| 13.1.4. File System Errors . . . . . . . . . . . . . . . . . 179 | | 13.1.4. File System Errors ...............................184 | |
| 13.1.5. State Management Errors . . . . . . . . . . . . . . 181 | | 13.1.5. State Management Errors ..........................186 | |
| 13.1.6. Security Errors . . . . . . . . . . . . . . . . . . 182 | | 13.1.6. Security Errors ..................................187 | |
| 13.1.7. Name Errors . . . . . . . . . . . . . . . . . . . . 183 | | 13.1.7. Name Errors ......................................187 | |
| 13.1.8. Locking Errors . . . . . . . . . . . . . . . . . . . 183 | | 13.1.8. Locking Errors ...................................188 | |
| 13.1.9. Reclaim Errors . . . . . . . . . . . . . . . . . . . 185 | | 13.1.9. Reclaim Errors ...................................190 | |
| 13.1.10. Client Management Errors . . . . . . . . . . . . . . 186 | | 13.1.10. Client Management Errors ........................191 | |
| 13.1.11. Attribute Handling Errors . . . . . . . . . . . . . 186 | | 13.1.11. Attribute Handling Errors .......................191 | |
| 13.1.12. Miscellaneous Errors . . . . . . . . . . . . . . . . 187 | | 13.1.12. Miscellaneous Errors ............................191 | |
| 13.2. Operations and their valid errors . . . . . . . . . . . 187 | | 13.2. Operations and Their Valid Errors .......................192 | |
| 13.3. Callback operations and their valid errors . . . . . . . 194 | | 13.3. Callback Operations and Their Valid Errors ..............200 | |
| 13.4. Errors and the operations that use them . . . . . . . . 195 | | 13.4. Errors and the Operations That Use Them .................201 | |
| 14. NFSv4 Requests . . . . . . . . . . . . . . . . . . . . . . . 200 | | 14. NFSv4 Requests ...............................................206 | |
| 14.1. Compound Procedure . . . . . . . . . . . . . . . . . . . 201 | | 14.1. COMPOUND Procedure ......................................207 | |
| 14.2. Evaluation of a Compound Request . . . . . . . . . . . . 202 | | 14.2. Evaluation of a COMPOUND Request ........................207 | |
| 14.3. Synchronous Modifying Operations . . . . . . . . . . . . 202 | | 14.3. Synchronous Modifying Operations ........................208 | |
| 14.4. Operation Values . . . . . . . . . . . . . . . . . . . . 203 | | 14.4. Operation Values ........................................208 | |
| 15. NFSv4 Procedures . . . . . . . . . . . . . . . . . . . . . . 203 | | 15. NFSv4 Procedures .............................................209 | |
| 15.1. Procedure 0: NULL - No Operation . . . . . . . . . . . . 203 | | 15.1. Procedure 0: NULL - No Operation ........................209 | |
| 15.2. Procedure 1: COMPOUND - Compound Operations . . . . . . 203 | | 15.2. Procedure 1: COMPOUND - COMPOUND Operations .............210 | |
| 15.3. Operation 3: ACCESS - Check Access Rights . . . . . . . 207 | | 16. NFSv4 Operations .............................................214 | |
| 15.4. Operation 4: CLOSE - Close File . . . . . . . . . . . . 210 | | 16.1. Operation 3: ACCESS - Check Access Rights ...............214 | |
| 15.5. Operation 5: COMMIT - Commit Cached Data . . . . . . . . 211 | | 16.2. Operation 4: CLOSE - Close File .........................217 | |
| 15.6. Operation 6: CREATE - Create a Non-Regular File Object . 213 | | 16.3. Operation 5: COMMIT - Commit Cached Data ................218 | |
| 15.7. Operation 7: DELEGPURGE - Purge Delegations Awaiting | | 16.4. Operation 6: CREATE - Create a Non-regular File Object ..221 | |
| Recovery . . . . . . . . . . . . . . . . . . . . . . . . 216 | | 16.5. Operation 7: DELEGPURGE - Purge Delegations | |
| 15.8. Operation 8: DELEGRETURN - Return Delegation . . . . . . 217 | | Awaiting Recovery .......................................224 | |
| 15.9. Operation 9: GETATTR - Get Attributes . . . . . . . . . 218 | | 16.6. Operation 8: DELEGRETURN - Return Delegation ............226 | |
| 15.10. Operation 10: GETFH - Get Current Filehandle . . . . . . 220 | | 16.7. Operation 9: GETATTR - Get Attributes ...................227 | |
| 15.11. Operation 11: LINK - Create Link to a File . . . . . . . 220 | | 16.8. Operation 10: GETFH - Get Current Filehandle ............229 | |
| 15.12. Operation 12: LOCK - Create Lock . . . . . . . . . . . . 222 | | 16.9. Operation 11: LINK - Create Link to a File ..............230 | |
| 15.13. Operation 13: LOCKT - Test For Lock . . . . . . . . . . 226 | | 16.10. Operation 12: LOCK - Create Lock .......................232 | |
| 15.14. Operation 14: LOCKU - Unlock File . . . . . . . . . . . 228 | | 16.11. Operation 13: LOCKT - Test for Lock ....................236 | |
| 15.15. Operation 15: LOOKUP - Lookup Filename . . . . . . . . . 229 | | 16.12. Operation 14: LOCKU - Unlock File ......................238 | |
| 15.16. Operation 16: LOOKUPP - Lookup Parent Directory . . . . 231 | | 16.13. Operation 15: LOOKUP - Look Up Filename ................240 | |
| 15.17. Operation 17: NVERIFY - Verify Difference in Attributes 232 | | 16.14. Operation 16: LOOKUPP - Look Up Parent Directory .......242 | |
| 15.18. Operation 18: OPEN - Open a Regular File . . . . . . . . 233 | | 16.15. Operation 17: NVERIFY - Verify Difference in | |
| 15.19. Operation 19: OPENATTR - Open Named Attribute Directory 243 | | Attributes .............................................243 | |
| 15.20. Operation 20: OPEN_CONFIRM - Confirm Open . . . . . . . 244 | | 16.16. Operation 18: OPEN - Open a Regular File ...............245 | |
| 15.21. Operation 21: OPEN_DOWNGRADE - Reduce Open File Access . 246 | | 16.17. Operation 19: OPENATTR - Open Named Attribute | |
| 15.22. Operation 22: PUTFH - Set Current Filehandle . . . . . . 248 | | Directory ..............................................256 | |
| 15.23. Operation 23: PUTPUBFH - Set Public Filehandle . . . . . 248 | | 16.18. Operation 20: OPEN_CONFIRM - Confirm Open ..............257 | |
| 15.24. Operation 24: PUTROOTFH - Set Root Filehandle . . . . . 250 | | 16.19. Operation 21: OPEN_DOWNGRADE - Reduce Open File | |
| 15.25. Operation 25: READ - Read from File . . . . . . . . . . 251 | | Access .................................................260 | |
| 15.26. Operation 26: READDIR - Read Directory . . . . . . . . . 253 | | 16.20. Operation 22: PUTFH - Set Current Filehandle ...........262 | |
| 15.27. Operation 27: READLINK - Read Symbolic Link . . . . . . 257 | | 16.21. Operation 23: PUTPUBFH - Set Public Filehandle .........263 | |
| 15.28. Operation 28: REMOVE - Remove Filesystem Object . . . . 258 | | 16.22. Operation 24: PUTROOTFH - Set Root Filehandle ..........265 | |
| 15.29. Operation 29: RENAME - Rename Directory Entry . . . . . 260 | | 16.23. Operation 25: READ - Read from File ....................266 | |
| 15.30. Operation 30: RENEW - Renew a Lease . . . . . . . . . . 262 | | 16.24. Operation 26: READDIR - Read Directory .................269 | |
| 15.31. Operation 31: RESTOREFH - Restore Saved Filehandle . . . 263 | | 16.25. Operation 27: READLINK - Read Symbolic Link ............273 | |
| 15.32. Operation 32: SAVEFH - Save Current Filehandle . . . . . 264 | | 16.26. Operation 28: REMOVE - Remove File System Object .......274 | |
| 15.33. Operation 33: SECINFO - Obtain Available Security . . . 265 | | 16.27. Operation 29: RENAME - Rename Directory Entry ..........276 | |
| 15.34. Operation 34: SETATTR - Set Attributes . . . . . . . . . 268 | | 16.28. Operation 30: RENEW - Renew a Lease ....................278 | |
| 15.35. Operation 35: SETCLIENTID - Negotiate Client ID . . . . 271 | | 16.29. Operation 31: RESTOREFH - Restore Saved Filehandle .....280 | |
| 15.36. Operation 36: SETCLIENTID_CONFIRM - Confirm Client ID . 275 | | 16.30. Operation 32: SAVEFH - Save Current Filehandle .........281 | |
| 15.37. Operation 37: VERIFY - Verify Same Attributes . . . . . 278 | | 16.31. Operation 33: SECINFO - Obtain Available Security ......282 | |
| 15.38. Operation 38: WRITE - Write to File . . . . . . . . . . 280 | | 16.32. Operation 34: SETATTR - Set Attributes .................286 | |
| 15.39. Operation 39: RELEASE_LOCKOWNER - Release Lockowner | | 16.33. Operation 35: SETCLIENTID - Negotiate Client ID ........289 | |
| State . . . . . . . . . . . . . . . . . . . . . . . . . 284 | | 16.34. Operation 36: SETCLIENTID_CONFIRM - Confirm Client ID ..293 | |
| 15.40. Operation 10044: ILLEGAL - Illegal operation . . . . . . 285 | | 16.35. Operation 37: VERIFY - Verify Same Attributes ..........297 | |
| 16. NFSv4 Callback Procedures . . . . . . . . . . . . . . . . . . 286 | | 16.36. Operation 38: WRITE - Write to File ....................299 | |
| 16.1. Procedure 0: CB_NULL - No Operation . . . . . . . . . . 286 | | 16.37. Operation 39: RELEASE_LOCKOWNER - Release | |
| 16.2. Procedure 1: CB_COMPOUND - Compound Operations . . . . . 286 | | Lock-Owner State .......................................304 | |
| 16.2.6. Operation 3: CB_GETATTR - Get Attributes . . . . . . 288 | | 16.38. Operation 10044: ILLEGAL - Illegal Operation ...........305 | |
| 16.2.7. Operation 4: CB_RECALL - Recall an Open Delegation . 289 | | 17. NFSv4 Callback Procedures ....................................306 | |
| 16.2.8. Operation 10044: CB_ILLEGAL - Illegal Callback | | 17.1. Procedure 0: CB_NULL - No Operation .....................306 | |
| Operation . . . . . . . . . . . . . . . . . . . . . 290 | | 17.2. Procedure 1: CB_COMPOUND - COMPOUND Operations ..........307 | |
| 17. Security Considerations . . . . . . . . . . . . . . . . . . . 291 | | 18. NFSv4 Callback Operations ....................................309 | |
| 18. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 293 | | 18.1. Operation 3: CB_GETATTR - Get Attributes ................309 | |
| 18.1. Named Attribute Definitions . . . . . . . . . . . . . . 293 | | 18.2. Operation 4: CB_RECALL - Recall an Open Delegation ......310 | |
| 18.1.1. Initial Registry . . . . . . . . . . . . . . . . . . 294 | | 18.3. Operation 10044: CB_ILLEGAL - Illegal Callback | |
| 18.1.2. Updating Registrations . . . . . . . . . . . . . . . 294 | | Operation ...............................................311 | |
| 19. References . . . . . . . . . . . . . . . . . . . . . . . . . 294 | | 19. Security Considerations ......................................312 | |
| 19.1. Normative References . . . . . . . . . . . . . . . . . . 294 | | 20. IANA Considerations ..........................................314 | |
| 19.2. Informative References . . . . . . . . . . . . . . . . . 296 | | 20.1. Named Attribute Definitions .............................314 | |
| Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 299 | | 20.1.1. Initial Registry .................................315 | |
| Appendix B. RFC Editor Notes . . . . . . . . . . . . . . . . . . 300 | | 20.1.2. Updating Registrations ...........................315 | |
| Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 300 | | 20.2. Updates to Existing IANA Registries .....................315 | |
| | | 21. References ...................................................316 | |
| | | 21.1. Normative References ....................................316 | |
| | | 21.2. Informative References ..................................318 | |
| | | Acknowledgments ..................................................322 | |
| | | Authors' Addresses ...............................................323 | |
| | | | |
| 1. Introduction | | 1. Introduction | |
| | | | |
|
| 1.1. NFS Version 4 Goals | | 1.1. Requirements Language | |
| | | | |
|
| The Network Filesystem version 4 (NFSv4) protocol is a further | | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", | |
| | | "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this | |
| | | document are to be interpreted as described in RFC 2119 [RFC2119], | |
| | | except where "REQUIRED" and "RECOMMENDED" are used as qualifiers to | |
| | | distinguish classes of attributes as described in Sections 1.4.3.2 | |
| | | and 5 of this document. | |
| | | | |
| | | 1.2. NFS Version 4 Goals | |
| | | | |
| | | The Network File System version 4 (NFSv4) protocol is a further | |
| revision of the NFS protocol defined already by versions 2 [RFC1094] | | revision of the NFS protocol defined already by versions 2 [RFC1094] | |
| and 3 [RFC1813]. It retains the essential characteristics of | | and 3 [RFC1813]. It retains the essential characteristics of | |
|
| previous versions: design for easy recovery, independent of transport | | previous versions: design for easy recovery; independent of transport | |
| protocols, operating systems and file systems, simplicity, and good | | protocols, operating systems, and file systems; simplicity; and good | |
| performance. The NFSv4 revision has the following goals: | | performance. The NFSv4 revision has the following goals: | |
| | | | |
| o Improved access and good performance on the Internet. | | o Improved access and good performance on the Internet. | |
| | | | |
| The protocol is designed to transit firewalls easily, perform well | | The protocol is designed to transit firewalls easily, perform well | |
| where latency is high and bandwidth is low, and scale to very | | where latency is high and bandwidth is low, and scale to very | |
| large numbers of clients per server. | | large numbers of clients per server. | |
| | | | |
| o Strong security with negotiation built into the protocol. | | o Strong security with negotiation built into the protocol. | |
| | | | |
| The protocol builds on the work of the Open Network Computing | | The protocol builds on the work of the Open Network Computing | |
| (ONC) Remote Procedure Call (RPC) working group in supporting the | | (ONC) Remote Procedure Call (RPC) working group in supporting the | |
| RPCSEC_GSS protocol (see both [RFC2203] and [RFC5403]). | | RPCSEC_GSS protocol (see both [RFC2203] and [RFC5403]). | |
|
| Additionally, the NFS version 4 protocol provides a mechanism to | | Additionally, the NFSv4 protocol provides a mechanism to allow | |
| allow clients and servers the ability to negotiate security and | | clients and servers the ability to negotiate security and require | |
| require clients and servers to support a minimal set of security | | clients and servers to support a minimal set of security schemes. | |
| schemes. | | | |
| | | | |
| o Good cross-platform interoperability. | | o Good cross-platform interoperability. | |
| | | | |
| The protocol features a file system model that provides a useful, | | The protocol features a file system model that provides a useful, | |
| common set of features that does not unduly favor one file system | | common set of features that does not unduly favor one file system | |
| or operating system over another. | | or operating system over another. | |
| | | | |
| o Designed for protocol extensions. | | o Designed for protocol extensions. | |
| | | | |
| The protocol is designed to accept standard extensions that do not | | The protocol is designed to accept standard extensions that do not | |
| compromise backward compatibility. | | compromise backward compatibility. | |
| | | | |
|
| This document, together with the companion XDR description document | | This document, together with the companion External Data | |
| [RFCNFSv4XDR], obsoletes [RFC3530] as the authoritative document | | Representation (XDR) description document [RFC7531], obsoletes | |
| describing NFSv4. It does not introduce any over-the-wire protocol | | [RFC3530] as the authoritative document describing NFSv4. It does | |
| changes, in the sense that previously valid requests remain valid. | | not introduce any over-the-wire protocol changes, in the sense that | |
| | | previously valid requests remain valid. | |
| | | | |
|
| 1.2. Definitions in the companion document NFS Version 4 Protocol are | | 1.3. Definitions in the Companion Document RFC 7531 Are Authoritative | |
| Authoritative | | | |
| | | | |
|
| [RFCNFSv4XDR], "Network File System (NFS) Version 4 External Data | | The "Network File System (NFS) Version 4 External Data Representation | |
| Representation Standard (XDR) Description", contains the definitions | | Standard (XDR) Description" [RFC7531] contains the definitions in XDR | |
| in XDR description language of the constructs used by the protocol. | | description language of the constructs used by the protocol. Inside | |
| Inside this document, several of the constructs are reproduced for | | this document, several of the constructs are reproduced for purposes | |
| purposes of explanation. The reader is warned of the possibility of | | of explanation. The reader is warned of the possibility of errors in | |
| errors in the reproduced constructs outside of [RFCNFSv4XDR]. For | | the reproduced constructs outside of [RFC7531]. For any part of the | |
| any part of the document that is inconsistent with [RFCNFSv4XDR], | | document that is inconsistent with [RFC7531], [RFC7531] is to be | |
| [RFCNFSv4XDR] is to be considered authoritative. | | considered authoritative. | |
| | | | |
|
| 1.3. Overview of NFSv4 Features | | 1.4. Overview of NFSv4 Features | |
| | | | |
| To provide a reasonable context for the reader, the major features of | | To provide a reasonable context for the reader, the major features of | |
|
| NFSv4 protocol will be reviewed in brief. This will be done to | | the NFSv4 protocol will be reviewed in brief. This is done to | |
| provide an appropriate context for both the reader who is familiar | | provide an appropriate context for both the reader who is familiar | |
| with the previous versions of the NFS protocol and the reader who is | | with the previous versions of the NFS protocol and the reader who is | |
| new to the NFS protocols. For the reader new to the NFS protocols, | | new to the NFS protocols. For the reader new to the NFS protocols, | |
| some fundamental knowledge is still expected. The reader should be | | some fundamental knowledge is still expected. The reader should be | |
|
| familiar with the XDR and RPC protocols as described in [RFC5531] and | | familiar with the XDR and RPC protocols as described in [RFC4506] and | |
| [RFC4506]. A basic knowledge of file systems and distributed file | | [RFC5531]. A basic knowledge of file systems and distributed file | |
| systems is expected as well. | | systems is expected as well. | |
| | | | |
|
| 1.3.1. RPC and Security | | 1.4.1. RPC and Security | |
| | | | |
|
| As with previous versions of NFS, the External Data Representation | | As with previous versions of NFS, the XDR and RPC mechanisms used for | |
| (XDR) and RPC mechanisms used for the NFSv4 protocol are those | | the NFSv4 protocol are those defined in [RFC4506] and [RFC5531]. To | |
| defined in [RFC5531] and [RFC4506]. To meet end to end security | | meet end-to-end security requirements, the RPCSEC_GSS framework (both | |
| requirements, the RPCSEC_GSS framework (both version 1 in [RFC2203] | | version 1 in [RFC2203] and version 2 in [RFC5403]) will be used to | |
| and version 2 in [RFC5403]) will be used to extend the basic RPC | | extend the basic RPC security. With the use of RPCSEC_GSS, various | |
| security. With the use of RPCSEC_GSS, various mechanisms can be | | mechanisms can be provided to offer authentication, integrity, and | |
| provided to offer authentication, integrity, and privacy to the NFS | | privacy to the NFSv4 protocol. Kerberos V5 will be used as described | |
| version 4 protocol. Kerberos V5 will be used as described in | | in [RFC4121] to provide one security framework. With the use of | |
| [RFC4121] to provide one security framework. With the use of | | RPCSEC_GSS, other mechanisms may also be specified and used for NFSv4 | |
| RPCSEC_GSS, other mechanisms may also be specified and used for NFS | | security. | |
| version 4 security. | | | |
| | | | |
| To enable in-band security negotiation, the NFSv4 protocol has added | | To enable in-band security negotiation, the NFSv4 protocol has added | |
|
| a new operation which provides the client with a method of querying | | a new operation that provides the client with a method of querying | |
| the server about its policies regarding which security mechanisms | | the server about its policies regarding which security mechanisms | |
| must be used for access to the server's file system resources. With | | must be used for access to the server's file system resources. With | |
| this, the client can securely match the security mechanism that meets | | this, the client can securely match the security mechanism that meets | |
| the policies specified at both the client and server. | | the policies specified at both the client and server. | |
| | | | |
|
| 1.3.2. Procedure and Operation Structure | | 1.4.2. Procedure and Operation Structure | |
| | | | |
| A significant departure from the previous versions of the NFS | | A significant departure from the previous versions of the NFS | |
| protocol is the introduction of the COMPOUND procedure. For the | | protocol is the introduction of the COMPOUND procedure. For the | |
|
| NFSv4 protocol, there are two RPC procedures, NULL and COMPOUND. The | | NFSv4 protocol, there are two RPC procedures: NULL and COMPOUND. The | |
| COMPOUND procedure is defined in terms of operations and these | | COMPOUND procedure is defined in terms of operations, and these | |
| operations correspond more closely to the traditional NFS procedures. | | operations correspond more closely to the traditional NFS procedures. | |
| | | | |
| With the use of the COMPOUND procedure, the client is able to build | | With the use of the COMPOUND procedure, the client is able to build | |
| simple or complex requests. These COMPOUND requests allow for a | | simple or complex requests. These COMPOUND requests allow for a | |
| reduction in the number of RPCs needed for logical file system | | reduction in the number of RPCs needed for logical file system | |
| operations. For example, without previous contact with a server a | | operations. For example, without previous contact with a server a | |
| client will be able to read data from a file in one request by | | client will be able to read data from a file in one request by | |
| combining LOOKUP, OPEN, and READ operations in a single COMPOUND RPC. | | combining LOOKUP, OPEN, and READ operations in a single COMPOUND RPC. | |
| With previous versions of the NFS protocol, this type of single | | With previous versions of the NFS protocol, this type of single | |
| request was not possible. | | request was not possible. | |
| | | | |
| The model used for COMPOUND is very simple. There is no logical OR | | The model used for COMPOUND is very simple. There is no logical OR | |
| or ANDing of operations. The operations combined within a COMPOUND | | or ANDing of operations. The operations combined within a COMPOUND | |
| request are evaluated in order by the server. Once an operation | | request are evaluated in order by the server. Once an operation | |
| returns a failing result, the evaluation ends and the results of all | | returns a failing result, the evaluation ends and the results of all | |
| evaluated operations are returned to the client. | | evaluated operations are returned to the client. | |
| | | | |
| The NFSv4 protocol continues to have the client refer to a file or | | The NFSv4 protocol continues to have the client refer to a file or | |
| directory at the server by a "filehandle". The COMPOUND procedure | | directory at the server by a "filehandle". The COMPOUND procedure | |
| has a method of passing a filehandle from one operation to another | | has a method of passing a filehandle from one operation to another | |
|
| within the sequence of operations. There is a concept of a "current | | within the sequence of operations. There is a concept of a current | |
| filehandle" and "saved filehandle". Most operations use the "current | | filehandle and a saved filehandle. Most operations use the current | |
| filehandle" as the file system object to operate upon. The "saved | | filehandle as the file system object to operate upon. The saved | |
| filehandle" is used as temporary filehandle storage within a COMPOUND | | filehandle is used as temporary filehandle storage within a COMPOUND | |
| procedure as well as an additional operand for certain operations. | | procedure as well as an additional operand for certain operations. | |
| | | | |
|
| 1.3.3. Filesystem Model | | 1.4.3. File System Model | |
| | | | |
| The general file system model used for the NFSv4 protocol is the same | | The general file system model used for the NFSv4 protocol is the same | |
|
| as previous versions. The server file system is hierarchical with | | as previous versions. The server file system is hierarchical, with | |
| the regular files contained within being treated as opaque byte | | the regular files contained within being treated as opaque byte | |
| streams. In a slight departure, file and directory names are encoded | | streams. In a slight departure, file and directory names are encoded | |
| with UTF-8 to deal with the basics of internationalization. | | with UTF-8 to deal with the basics of internationalization. | |
| | | | |
| The NFSv4 protocol does not require a separate protocol to provide | | The NFSv4 protocol does not require a separate protocol to provide | |
|
| for the initial mapping between path name and filehandle. Instead of | | for the initial mapping between pathname and filehandle. Instead of | |
| using the older MOUNT protocol for this mapping, the server provides | | using the older MOUNT protocol for this mapping, the server provides | |
|
| a ROOT filehandle that represents the logical root or top of the file | | a root filehandle that represents the logical root or top of the file | |
| system tree provided by the server. The server provides multiple | | system tree provided by the server. The server provides multiple | |
|
| file systems by gluing them together with pseudo file systems. These | | file systems by gluing them together with pseudo-file systems. These | |
| pseudo file systems provide for potential gaps in the path names | | pseudo-file systems provide for potential gaps in the pathnames | |
| between real file systems. | | between real file systems. | |
| | | | |
|
| 1.3.3.1. Filehandle Types | | 1.4.3.1. Filehandle Types | |
| | | | |
| In previous versions of the NFS protocol, the filehandle provided by | | In previous versions of the NFS protocol, the filehandle provided by | |
| the server was guaranteed to be valid or persistent for the lifetime | | the server was guaranteed to be valid or persistent for the lifetime | |
| of the file system object to which it referred. For some server | | of the file system object to which it referred. For some server | |
| implementations, this persistence requirement has been difficult to | | implementations, this persistence requirement has been difficult to | |
| meet. For the NFSv4 protocol, this requirement has been relaxed by | | meet. For the NFSv4 protocol, this requirement has been relaxed by | |
|
| introducing another type of filehandle, volatile. With persistent | | introducing another type of filehandle -- volatile. With persistent | |
| and volatile filehandle types, the server implementation can match | | and volatile filehandle types, the server implementation can match | |
| the abilities of the file system at the server along with the | | the abilities of the file system at the server along with the | |
| operating environment. The client will have knowledge of the type of | | operating environment. The client will have knowledge of the type of | |
| filehandle being provided by the server and can be prepared to deal | | filehandle being provided by the server and can be prepared to deal | |
| with the semantics of each. | | with the semantics of each. | |
| | | | |
|
| 1.3.3.2. Attribute Types | | 1.4.3.2. Attribute Types | |
| | | | |
| The NFSv4 protocol has a rich and extensible file object attribute | | The NFSv4 protocol has a rich and extensible file object attribute | |
| structure, which is divided into REQUIRED, RECOMMENDED, and named | | structure, which is divided into REQUIRED, RECOMMENDED, and named | |
| attributes (see Section 5). | | attributes (see Section 5). | |
| | | | |
| Several (but not all) of the REQUIRED attributes are derived from the | | Several (but not all) of the REQUIRED attributes are derived from the | |
|
| attributes of NFSv3 (see definition of the fattr3 data type in | | attributes of NFSv3 (see the definition of the fattr3 data type in | |
| [RFC1813]). An example of a REQUIRED attribute is the file object's | | [RFC1813]). An example of a REQUIRED attribute is the file object's | |
| type (Section 5.8.1.2) so that regular files can be distinguished | | type (Section 5.8.1.2) so that regular files can be distinguished | |
| from directories (also known as folders in some operating | | from directories (also known as folders in some operating | |
| environments) and other types of objects. REQUIRED attributes are | | environments) and other types of objects. REQUIRED attributes are | |
| discussed in Section 5.1. | | discussed in Section 5.1. | |
| | | | |
| An example of the RECOMMENDED attributes is an acl (Section 6.2.1). | | An example of the RECOMMENDED attributes is an acl (Section 6.2.1). | |
| This attribute defines an Access Control List (ACL) on a file object. | | This attribute defines an Access Control List (ACL) on a file object. | |
| An ACL provides file access control beyond the model used in NFSv3. | | An ACL provides file access control beyond the model used in NFSv3. | |
| The ACL definition allows for specification of specific sets of | | The ACL definition allows for specification of specific sets of | |
| permissions for individual users and groups. In addition, ACL | | permissions for individual users and groups. In addition, ACL | |
| inheritance allows propagation of access permissions and restriction | | inheritance allows propagation of access permissions and restriction | |
| down a directory tree as file system objects are created. | | down a directory tree as file system objects are created. | |
| RECOMMENDED attributes are discussed in Section 5.2. | | RECOMMENDED attributes are discussed in Section 5.2. | |
| | | | |
| A named attribute is an opaque byte stream that is associated with a | | A named attribute is an opaque byte stream that is associated with a | |
| directory or file and referred to by a string name. Named attributes | | directory or file and referred to by a string name. Named attributes | |
| are meant to be used by client applications as a method to associate | | are meant to be used by client applications as a method to associate | |
| application-specific data with a regular file or directory. NFSv4.1 | | application-specific data with a regular file or directory. NFSv4.1 | |
| modifies named attributes relative to NFSv4.0 by tightening the | | modifies named attributes relative to NFSv4.0 by tightening the | |
|
| allowed operations in order to prevent the development of non- | | allowed operations in order to prevent the development of | |
| interoperable implementations. Named attributes are discussed in | | non-interoperable implementations. Named attributes are discussed in | |
| Section 5.3. | | Section 5.3. | |
| | | | |
|
| 1.3.3.3. Multi-server Namespace | | 1.4.3.3. Multi-Server Namespace | |
| | | | |
| A single-server namespace is the file system hierarchy that the | | A single-server namespace is the file system hierarchy that the | |
| server presents for remote access. It is a proper subset of all the | | server presents for remote access. It is a proper subset of all the | |
| file systems available locally. NFSv4 contains a number of features | | file systems available locally. NFSv4 contains a number of features | |
| to allow implementation of namespaces that cross server boundaries | | to allow implementation of namespaces that cross server boundaries | |
| and that allow and facilitate a non-disruptive transfer of support | | and that allow and facilitate a non-disruptive transfer of support | |
| for individual file systems between servers. They are all based upon | | for individual file systems between servers. They are all based upon | |
| attributes that allow one file system to specify alternative or new | | attributes that allow one file system to specify alternative or new | |
|
| locations for that file system. I.e., just as a client might | | locations for that file system. That is, just as a client might | |
| traverse across local file systems on a single server, it can now | | traverse across local file systems on a single server, it can now | |
| traverse to a remote file system on a different server. | | traverse to a remote file system on a different server. | |
| | | | |
| These attributes may be used together with the concept of absent file | | These attributes may be used together with the concept of absent file | |
| systems, which provide specifications for additional locations but no | | systems, which provide specifications for additional locations but no | |
| actual file system content. This allows a number of important | | actual file system content. This allows a number of important | |
| facilities: | | facilities: | |
| | | | |
| o Location attributes may be used with absent file systems to | | o Location attributes may be used with absent file systems to | |
| implement referrals whereby one server may direct the client to a | | implement referrals whereby one server may direct the client to a | |
| | | | |
| skipping to change at page 12, line 14 | | skipping to change at page 12, line 37 | |
| | | | |
| o Location attributes may be provided for present file systems to | | o Location attributes may be provided for present file systems to | |
| provide the locations of alternative file system instances or | | provide the locations of alternative file system instances or | |
| replicas to be used in the event that the current file system | | replicas to be used in the event that the current file system | |
| instance becomes unavailable. | | instance becomes unavailable. | |
| | | | |
| o Location attributes may be provided when a previously present file | | o Location attributes may be provided when a previously present file | |
| system becomes absent. This allows non-disruptive migration of | | system becomes absent. This allows non-disruptive migration of | |
| file systems to alternative servers. | | file systems to alternative servers. | |
| | | | |
|
| 1.3.4. OPEN and CLOSE | | 1.4.4. OPEN and CLOSE | |
| | | | |
| The NFSv4 protocol introduces OPEN and CLOSE operations. The OPEN | | The NFSv4 protocol introduces OPEN and CLOSE operations. The OPEN | |
| operation provides a single point where file lookup, creation, and | | operation provides a single point where file lookup, creation, and | |
| share semantics (see Section 9.9) can be combined. The CLOSE | | share semantics (see Section 9.9) can be combined. The CLOSE | |
| operation also provides for the release of state accumulated by OPEN. | | operation also provides for the release of state accumulated by OPEN. | |
| | | | |
|
| 1.3.5. File Locking | | 1.4.5. File Locking | |
| | | | |
|
| With the NFSv4 protocol, the support for byte range file locking is | | With the NFSv4 protocol, the support for byte-range file locking is | |
| part of the NFS protocol. The file locking support is structured so | | part of the NFS protocol. The file locking support is structured so | |
| that an RPC callback mechanism is not required. This is a departure | | that an RPC callback mechanism is not required. This is a departure | |
| from the previous versions of the NFS file locking protocol, Network | | from the previous versions of the NFS file locking protocol, Network | |
| Lock Manager (NLM) [RFC1813]. The state associated with file locks | | Lock Manager (NLM) [RFC1813]. The state associated with file locks | |
| is maintained at the server under a lease-based model. The server | | is maintained at the server under a lease-based model. The server | |
|
| defines a single lease period for all state held by a NFS client. If | | defines a single lease period for all state held by an NFS client. | |
| the client does not renew its lease within the defined period, all | | | |
| | | If the client does not renew its lease within the defined period, all | |
| state associated with the client's lease may be released by the | | state associated with the client's lease may be released by the | |
|
| server. The client may renew its lease with use of the RENEW | | server. The client may renew its lease by use of the RENEW operation | |
| operation or implicitly by use of other operations (primarily READ). | | or implicitly by use of other operations (primarily READ). | |
| | | | |
|
| 1.3.6. Client Caching and Delegation | | 1.4.6. Client Caching and Delegation | |
| | | | |
| The file, attribute, and directory caching for the NFSv4 protocol is | | The file, attribute, and directory caching for the NFSv4 protocol is | |
| similar to previous versions. Attributes and directory information | | similar to previous versions. Attributes and directory information | |
| are cached for a duration determined by the client. At the end of a | | are cached for a duration determined by the client. At the end of a | |
| predefined timeout, the client will query the server to see if the | | predefined timeout, the client will query the server to see if the | |
| related file system object has been updated. | | related file system object has been updated. | |
| | | | |
| For file data, the client checks its cache validity when the file is | | For file data, the client checks its cache validity when the file is | |
| opened. A query is sent to the server to determine if the file has | | opened. A query is sent to the server to determine if the file has | |
| been changed. Based on this information, the client determines if | | been changed. Based on this information, the client determines if | |
|
| the data cache for the file should kept or released. Also, when the | | the data cache for the file should be kept or released. Also, when | |
| file is closed, any modified data is written to the server. | | the file is closed, any modified data is written to the server. | |
| | | | |
| If an application wants to serialize access to file data, file | | If an application wants to serialize access to file data, file | |
| locking of the file data ranges in question should be used. | | locking of the file data ranges in question should be used. | |
| | | | |
| The major addition to NFSv4 in the area of caching is the ability of | | The major addition to NFSv4 in the area of caching is the ability of | |
| the server to delegate certain responsibilities to the client. When | | the server to delegate certain responsibilities to the client. When | |
| the server grants a delegation for a file to a client, the client is | | the server grants a delegation for a file to a client, the client is | |
| guaranteed certain semantics with respect to the sharing of that file | | guaranteed certain semantics with respect to the sharing of that file | |
| with other clients. At OPEN, the server may provide the client | | with other clients. At OPEN, the server may provide the client | |
| either a read (OPEN_DELEGATE_READ) or a write (OPEN_DELEGATE_WRITE) | | either a read (OPEN_DELEGATE_READ) or a write (OPEN_DELEGATE_WRITE) | |
| delegation for the file (see Section 10.4). If the client is granted | | delegation for the file (see Section 10.4). If the client is granted | |
|
| a OPEN_DELEGATE_READ delegation, it is assured that no other client | | an OPEN_DELEGATE_READ delegation, it is assured that no other client | |
| has the ability to write to the file for the duration of the | | has the ability to write to the file for the duration of the | |
|
| delegation. If the client is granted a OPEN_DELEGATE_WRITE | | delegation. If the client is granted an OPEN_DELEGATE_WRITE | |
| delegation, the client is assured that no other client has read or | | delegation, the client is assured that no other client has read or | |
| write access to the file. | | write access to the file. | |
| | | | |
| Delegations can be recalled by the server. If another client | | Delegations can be recalled by the server. If another client | |
| requests access to the file in such a way that the access conflicts | | requests access to the file in such a way that the access conflicts | |
| with the granted delegation, the server is able to notify the initial | | with the granted delegation, the server is able to notify the initial | |
| client and recall the delegation. This requires that a callback path | | client and recall the delegation. This requires that a callback path | |
| exist between the server and client. If this callback path does not | | exist between the server and client. If this callback path does not | |
| exist, then delegations cannot be granted. The essence of a | | exist, then delegations cannot be granted. The essence of a | |
| delegation is that it allows the client to locally service operations | | delegation is that it allows the client to locally service operations | |
| such as OPEN, CLOSE, LOCK, LOCKU, READ, or WRITE without immediate | | such as OPEN, CLOSE, LOCK, LOCKU, READ, or WRITE without immediate | |
| interaction with the server. | | interaction with the server. | |
| | | | |
|
| 1.4. General Definitions | | 1.5. General Definitions | |
| | | | |
| The following definitions are provided for the purpose of providing | | The following definitions are provided for the purpose of providing | |
| an appropriate context for the reader. | | an appropriate context for the reader. | |
| | | | |
|
| Anonymous Stateid: Special locking object defined in | | | |
| Section 9.1.4.3. | | | |
| | | | |
| Absent File System: A file system is "absent" when a namespace | | Absent File System: A file system is "absent" when a namespace | |
| component does not have a backing file system. | | component does not have a backing file system. | |
| | | | |
|
| Byte: In this document, a byte is an octet, i.e., a datum exactly 8 | | Anonymous Stateid: The Anonymous Stateid is a special locking object | |
| bits in length. | | and is defined in Section 9.1.4.3. | |
| | | | |
| | | Byte: In this document, a byte is an octet, i.e., a datum exactly | |
| | | 8 bits in length. | |
| | | | |
| Client: The client is the entity that accesses the NFS server's | | Client: The client is the entity that accesses the NFS server's | |
| resources. The client may be an application that contains the | | resources. The client may be an application that contains the | |
| logic to access the NFS server directly. The client may also be | | logic to access the NFS server directly. The client may also be | |
| the traditional operating system client that provides remote file | | the traditional operating system client that provides remote file | |
| system services for a set of applications. | | system services for a set of applications. | |
| | | | |
| With reference to byte-range locking, the client is also the | | With reference to byte-range locking, the client is also the | |
| entity that maintains a set of locks on behalf of one or more | | entity that maintains a set of locks on behalf of one or more | |
| applications. This client is responsible for crash or failure | | applications. This client is responsible for crash or failure | |
| recovery for those locks it manages. | | recovery for those locks it manages. | |
| | | | |
| Note that multiple clients may share the same transport and | | Note that multiple clients may share the same transport and | |
|
| connection and multiple clients may exist on the same network | | connection, and multiple clients may exist on the same network | |
| node. | | node. | |
| | | | |
|
| Client ID: A 64-bit quantity used as a unique, short-hand reference | | Client ID: The client ID is a 64-bit quantity used as a unique, | |
| to a client supplied Verifier and ID. The server is responsible | | shorthand reference to a client-supplied verifier and ID. The | |
| for supplying the Client ID. | | server is responsible for supplying the client ID. | |
| | | | |
| File System: The file system is the collection of objects on a | | File System: The file system is the collection of objects on a | |
| server that share the same fsid attribute (see Section 5.8.1.9). | | server that share the same fsid attribute (see Section 5.8.1.9). | |
| | | | |
|
| Lease: An interval of time defined by the server for which the | | Lease: A lease is an interval of time defined by the server for | |
| client is irrevocably granted a lock. At the end of a lease | | which the client is irrevocably granted a lock. At the end of a | |
| period the lock may be revoked if the lease has not been extended. | | lease period the lock may be revoked if the lease has not been | |
| The lock must be revoked if a conflicting lock has been granted | | extended. The lock must be revoked if a conflicting lock has been | |
| after the lease interval. | | granted after the lease interval. | |
| | | | |
| All leases granted by a server have the same fixed duration. Note | | All leases granted by a server have the same fixed duration. Note | |
| that the fixed interval duration was chosen to alleviate the | | that the fixed interval duration was chosen to alleviate the | |
|
| expense a server would have in maintaining state about variable | | expense a server would have in maintaining state about variable- | |
| length leases across server failures. | | length leases across server failures. | |
| | | | |
|
| Lock: The term "lock" is used to refer to both record (byte-range) | | Lock: The term "lock" is used to refer to record (byte-range) locks | |
| locks as well as share reservations unless specifically stated | | as well as share reservations unless specifically stated | |
| otherwise. | | otherwise. | |
| | | | |
|
| Lock-Owner: Each byte-range lock is associated with a specific lock- | | Lock-Owner: Each byte-range lock is associated with a specific | |
| owner and an open-owner. The lock-owner consists of a Client ID | | lock-owner and an open-owner. The lock-owner consists of a | |
| and an opaque owner string. The client presents this to the | | client ID and an opaque owner string. The client presents this to | |
| server to establish the ownership of the byte-range lock as | | the server to establish the ownership of the byte-range lock as | |
| needed. | | needed. | |
| | | | |
| Open-Owner: Each open file is associated with a specific open-owner, | | Open-Owner: Each open file is associated with a specific open-owner, | |
|
| which consists of a Client ID and an opaque owner string. The | | which consists of a client ID and an opaque owner string. The | |
| client presents this to the server to establish the ownership of | | client presents this to the server to establish the ownership of | |
| the open as needed. | | the open as needed. | |
| | | | |
|
| READ Bypass Stateid: Special locking object defined in | | READ Bypass Stateid: The READ Bypass Stateid is a special locking | |
| Section 9.1.4.3. | | object and is defined in Section 9.1.4.3. | |
| | | | |
|
| Server: The "Server" is the entity responsible for coordinating | | Server: The "server" is the entity responsible for coordinating | |
| client access to a set of file systems. | | client access to a set of file systems. | |
| | | | |
| Stable Storage: NFSv4 servers must be able to recover without data | | Stable Storage: NFSv4 servers must be able to recover without data | |
| loss from multiple power failures (including cascading power | | loss from multiple power failures (including cascading power | |
| failures, that is, several power failures in quick succession), | | failures, that is, several power failures in quick succession), | |
| operating system failures, and hardware failure of components | | operating system failures, and hardware failure of components | |
| other than the storage medium itself (for example, disk, | | other than the storage medium itself (for example, disk, | |
|
| nonvolatile RAM). | | non-volatile RAM). | |
| | | | |
| Some examples of stable storage that are allowable for an NFS | | Some examples of stable storage that are allowable for an NFS | |
| server include: | | server include: | |
| | | | |
|
| (1) Media commit of data, that is, the modified data has been | | (1) Media commit of data. That is, the modified data has been | |
| successfully written to the disk media, for example, the disk | | successfully written to the disk media -- for example, the | |
| platter. | | disk platter. | |
| | | | |
| (2) An immediate reply disk drive with battery-backed on-drive | | (2) An immediate reply disk drive with battery-backed on-drive | |
| intermediate storage or uninterruptible power system (UPS). | | intermediate storage or uninterruptible power system (UPS). | |
| | | | |
| (3) Server commit of data with battery-backed intermediate | | (3) Server commit of data with battery-backed intermediate | |
| storage and recovery software. | | storage and recovery software. | |
| | | | |
|
| (4) Cache commit with uninterruptible power system (UPS) and | | (4) Cache commit with UPS and recovery software. | |
| recovery software. | | | |
| | | | |
| Stateid: A stateid is a 128-bit quantity returned by a server that | | Stateid: A stateid is a 128-bit quantity returned by a server that | |
| uniquely identifies the open and locking states provided by the | | uniquely identifies the open and locking states provided by the | |
| server for a specific open-owner or lock-owner/open-owner pair for | | server for a specific open-owner or lock-owner/open-owner pair for | |
| a specific file and type of lock. | | a specific file and type of lock. | |
| | | | |
|
| Verifier: A 64-bit quantity generated by the client that the server | | Verifier: A verifier is a 64-bit quantity generated by the client | |
| can use to determine if the client has restarted and lost all | | that the server can use to determine if the client has restarted | |
| previous lock state. | | and lost all previous lock state. | |
| | | | |
|
| 1.5. Changes since RFC 3530 | | 1.6. Changes since RFC 3530 | |
| | | | |
| The main changes from RFC 3530 [RFC3530] are: | | The main changes from RFC 3530 [RFC3530] are: | |
| | | | |
| o The XDR definition has been moved to a companion document | | o The XDR definition has been moved to a companion document | |
|
| [RFCNFSv4XDR]. | | [RFC7531]. | |
| | | | |
| o The IETF intellectual property statements were updated to the | | o The IETF intellectual property statements were updated to the | |
| latest version. | | latest version. | |
| | | | |
| o There is a restructured and more complete explanation of multi- | | o There is a restructured and more complete explanation of multi- | |
| server namespace features. | | server namespace features. | |
| | | | |
|
| o The handling of domain names were updated to reflect | | o The handling of domain names was updated to reflect | |
| Internationalized Domain Names in Applications (IDNA) [RFC5891]. | | Internationalized Domain Names in Applications (IDNA) [RFC5891]. | |
| | | | |
| o The previously required LIPKEY and SPKM-3 security mechanisms have | | o The previously required LIPKEY and SPKM-3 security mechanisms have | |
| been removed. | | been removed. | |
| | | | |
|
| o Some clarification on a client re-establishing callback | | o Some clarification was provided regarding a client re-establishing | |
| information to the new server if state has been migrated. | | callback information to the new server if state has been migrated. | |
| | | | |
|
| o A third edge case was added for Courtesy locks and network | | o A third edge case was added for courtesy locks and network | |
| partitions. | | partitions. | |
| | | | |
| o The definition of stateid was strengthened. | | o The definition of stateid was strengthened. | |
| | | | |
|
| 1.6. Changes between RFC 3010 and RFC3530 | | 1.7. Changes between RFC 3010 and RFC 3530 | |
| | | | |
| The definition of the NFSv4 protocol in [RFC3530] replaced and | | The definition of the NFSv4 protocol in [RFC3530] replaced and | |
| obsoleted the definition present in [RFC3010]. While portions of the | | obsoleted the definition present in [RFC3010]. While portions of the | |
| two documents remained the same, there were substantive changes in | | two documents remained the same, there were substantive changes in | |
| others. The changes made between [RFC3010] and [RFC3530] reflect | | others. The changes made between [RFC3010] and [RFC3530] reflect | |
| implementation experience and further review of the protocol. | | implementation experience and further review of the protocol. | |
| | | | |
|
| The following list is not all inclusive of all changes but presents | | The following list is not inclusive of all changes but presents some | |
| some of the most notable changes or additions made: | | of the most notable changes or additions made: | |
| | | | |
| o The state model has added an open_owner4 identifier. This was | | o The state model has added an open_owner4 identifier. This was | |
|
| done to accommodate Posix based clients and the model they use for | | done to accommodate POSIX-based clients and the model they use for | |
| file locking. For Posix clients, an open_owner4 would correspond | | file locking. For POSIX clients, an open_owner4 would correspond | |
| to a file descriptor potentially shared amongst a set of processes | | to a file descriptor potentially shared amongst a set of processes | |
| and the lock_owner4 identifier would correspond to a process that | | and the lock_owner4 identifier would correspond to a process that | |
| is locking a file. | | is locking a file. | |
| | | | |
|
| o Clarifications and error conditions were added for the handling of | | o Added clarifications and error conditions for the handling of the | |
| the owner and group attributes. Since these attributes are string | | owner and group attributes. Since these attributes are string | |
| based (as opposed to the numeric uid/gid of previous versions of | | based (as opposed to the numeric uid/gid of previous versions of | |
| NFS), translations may not be available and hence the changes | | NFS), translations may not be available and hence the changes | |
| made. | | made. | |
| | | | |
|
| o Clarifications for the ACL and mode attributes to address | | o Added clarifications for the ACL and mode attributes to address | |
| evaluation and partial support. | | evaluation and partial support. | |
| | | | |
|
| o For identifiers that are defined as XDR opaque, limits were set on | | o For identifiers that are defined as XDR opaque, set limits on | |
| their size. | | their size. | |
| | | | |
|
| o Added the mounted_on_fileid attribute to allow Posix clients to | | o Added the mounted_on_fileid attribute to allow POSIX clients to | |
| correctly construct local mounts. | | correctly construct local mounts. | |
| | | | |
| o Modified the SETCLIENTID/SETCLIENTID_CONFIRM operations to deal | | o Modified the SETCLIENTID/SETCLIENTID_CONFIRM operations to deal | |
| correctly with confirmation details along with adding the ability | | correctly with confirmation details along with adding the ability | |
| to specify new client callback information. Also added | | to specify new client callback information. Also added | |
| clarification of the callback information itself. | | clarification of the callback information itself. | |
| | | | |
| o Added a new operation RELEASE_LOCKOWNER to enable notifying the | | o Added a new operation RELEASE_LOCKOWNER to enable notifying the | |
| server that a lock_owner4 will no longer be used by the client. | | server that a lock_owner4 will no longer be used by the client. | |
| | | | |
|
| o RENEW operation changes to identify the client correctly and allow | | o Added RENEW operation changes to identify the client correctly and | |
| for additional error returns. | | allow for additional error returns. | |
| | | | |
|
| o Verify error return possibilities for all operations. | | o Verified error return possibilities for all operations. | |
| | | | |
|
| o Remove use of the pathname4 data type from LOOKUP and OPEN in | | o Removed use of the pathname4 data type from LOOKUP and OPEN in | |
| favor of having the client construct a sequence of LOOKUP | | favor of having the client construct a sequence of LOOKUP | |
| operations to achieve the same effect. | | operations to achieve the same effect. | |
| | | | |
| 2. Protocol Data Types | | 2. Protocol Data Types | |
| | | | |
|
| The syntax and semantics to describe the data types of the NFS | | The syntax and semantics to describe the data types of the NFSv4 | |
| version 4 protocol are defined in the XDR [RFC4506] and RPC [RFC5531] | | protocol are defined in the XDR [RFC4506] and RPC [RFC5531] | |
| documents. The next sections build upon the XDR data types to define | | documents. The next sections build upon the XDR data types to define | |
| types and structures specific to this protocol. As a reminder, the | | types and structures specific to this protocol. As a reminder, the | |
|
| size constants and definitive definitions can be found in | | size constants and authoritative definitions can be found in | |
| [RFCNFSv4XDR]. | | [RFC7531]. | |
| | | | |
| 2.1. Basic Data Types | | 2.1. Basic Data Types | |
| | | | |
|
| These are the base NFSv4 data types. | | Table 1 lists the base NFSv4 data types. | |
| | | | |
| +-----------------+-------------------------------------------------+ | | +-----------------+-------------------------------------------------+ | |
| | Data Type | Definition | | | | Data Type | Definition | | |
| +-----------------+-------------------------------------------------+ | | +-----------------+-------------------------------------------------+ | |
| | int32_t | typedef int int32_t; | | | | int32_t | typedef int int32_t; | | |
|
| | | | | | | |
| | uint32_t | typedef unsigned int uint32_t; | | | | uint32_t | typedef unsigned int uint32_t; | | |
|
| | | | | | | |
| | int64_t | typedef hyper int64_t; | | | | int64_t | typedef hyper int64_t; | | |
|
| | | | | | | |
| | uint64_t | typedef unsigned hyper uint64_t; | | | | uint64_t | typedef unsigned hyper uint64_t; | | |
|
| | | | | | | |
| | attrlist4 | typedef opaque attrlist4<>; | | | | attrlist4 | typedef opaque attrlist4<>; | | |
|
| | | | | | | |
| | | Used for file/directory attributes. | | | | | Used for file/directory attributes. | | |
|
| | | | | | | |
| | bitmap4 | typedef uint32_t bitmap4<>; | | | | bitmap4 | typedef uint32_t bitmap4<>; | | |
|
| | | | | | | |
| | | Used in attribute array encoding. | | | | | Used in attribute array encoding. | | |
|
| | | | | | | |
| | changeid4 | typedef uint64_t changeid4; | | | | changeid4 | typedef uint64_t changeid4; | | |
|
| | | | | | | |
| | | Used in the definition of change_info4. | | | | | Used in the definition of change_info4. | | |
|
| | | | | | | |
| | clientid4 | typedef uint64_t clientid4; | | | | clientid4 | typedef uint64_t clientid4; | | |
|
| | | | | | | |
| | | Shorthand reference to client identification. | | | | | Shorthand reference to client identification. | | |
|
| | | | | | | |
| | count4 | typedef uint32_t count4; | | | | count4 | typedef uint32_t count4; | | |
|
| | | | | | | |
| | | Various count parameters (READ, WRITE, COMMIT). | | | | | Various count parameters (READ, WRITE, COMMIT). | | |
|
| | | | | | | |
| | length4 | typedef uint64_t length4; | | | | length4 | typedef uint64_t length4; | | |
|
| | | | | | | |
| | | Describes LOCK lengths. | | | | | Describes LOCK lengths. | | |
|
| | | | | | | |
| | mode4 | typedef uint32_t mode4; | | | | mode4 | typedef uint32_t mode4; | | |
|
| | | | | | | |
| | | Mode attribute data type. | | | | | Mode attribute data type. | | |
|
| | | | | | | |
| | nfs_cookie4 | typedef uint64_t nfs_cookie4; | | | | nfs_cookie4 | typedef uint64_t nfs_cookie4; | | |
|
| | | | | | | |
| | | Opaque cookie value for READDIR. | | | | | Opaque cookie value for READDIR. | | |
|
| | | | | | | |
| | nfs_fh4 | typedef opaque nfs_fh4<NFS4_FHSIZE>; | | | | nfs_fh4 | typedef opaque nfs_fh4<NFS4_FHSIZE>; | | |
|
| | | | | | | |
| | | Filehandle definition. | | | | | Filehandle definition. | | |
|
| | | | | | | |
| | nfs_ftype4 | enum nfs_ftype4; | | | | nfs_ftype4 | enum nfs_ftype4; | | |
|
| | | | | | | |
| | | Various defined file types. | | | | | Various defined file types. | | |
|
| | | | | | | |
| | nfsstat4 | enum nfsstat4; | | | | nfsstat4 | enum nfsstat4; | | |
|
| | | | | | | |
| | | Return value for operations. | | | | | Return value for operations. | | |
|
| | | | | | | |
| | nfs_lease4 | typedef uint32_t nfs_lease4; | | | | nfs_lease4 | typedef uint32_t nfs_lease4; | | |
|
| | | | | | | |
| | | Duration of a lease in seconds. | | | | | Duration of a lease in seconds. | | |
|
| | | | | | | |
| | offset4 | typedef uint64_t offset4; | | | | offset4 | typedef uint64_t offset4; | | |
|
| | | | | | | |
| | | Various offset designations (READ, WRITE, LOCK, | | | | | Various offset designations (READ, WRITE, LOCK, | | |
| | | COMMIT). | | | | | COMMIT). | | |
|
| | | | | | | |
| | qop4 | typedef uint32_t qop4; | | | | qop4 | typedef uint32_t qop4; | | |
|
| | | | | | | |
| | | Quality of protection designation in SECINFO. | | | | | Quality of protection designation in SECINFO. | | |
|
| | | | | | | |
| | sec_oid4 | typedef opaque sec_oid4<>; | | | | sec_oid4 | typedef opaque sec_oid4<>; | | |
|
| | | Security Object Identifier. The sec_oid4 data | | | | | | | |
| | | type is not really opaque. Instead it contains | | | | | Security Object Identifier. The sec_oid4 data | | |
| | | an ASN.1 OBJECT IDENTIFIER as used by GSS-API | | | | | type is not really opaque. Instead, it | | |
| | | in the mech_type argument to | | | | | contains an ASN.1 OBJECT IDENTIFIER as used by | | |
| | | GSS_Init_sec_context. See [RFC2743] for | | | | | GSS-API in the mech_type argument to | | |
| | | | | GSS_Init_sec_context. See [RFC2743] for | | |
| | | details. | | | | | details. | | |
|
| | | | | | | |
| | seqid4 | typedef uint32_t seqid4; | | | | seqid4 | typedef uint32_t seqid4; | | |
|
| | | | | | | |
| | | Sequence identifier used for file locking. | | | | | Sequence identifier used for file locking. | | |
|
| | | | | | | |
| | utf8string | typedef opaque utf8string<>; | | | | utf8string | typedef opaque utf8string<>; | | |
|
| | | | | | | |
| | | UTF-8 encoding for strings. | | | | | UTF-8 encoding for strings. | | |
|
| | | | | | | |
| | utf8str_cis | typedef utf8string utf8str_cis; | | | | utf8str_cis | typedef utf8string utf8str_cis; | | |
|
| | | Case insensitive UTF-8 string. | | | | | | | |
| | | | | Case-insensitive UTF-8 string. | | |
| | | | | | | |
| | utf8str_cs | typedef utf8string utf8str_cs; | | | | utf8str_cs | typedef utf8string utf8str_cs; | | |
|
| | | Case sensitive UTF-8 string. | | | | | | | |
| | | | | Case-sensitive UTF-8 string. | | |
| | | | | | | |
| | utf8str_mixed | typedef utf8string utf8str_mixed; | | | | utf8str_mixed | typedef utf8string utf8str_mixed; | | |
|
| | | UTF-8 strings with a case sensitive prefix and | | | | | | | |
| | | a case insensitive suffix. | | | | | UTF-8 strings with a case-sensitive prefix and | | |
| | | | | a case-insensitive suffix. | | |
| | | | | | | |
| | component4 | typedef utf8str_cs component4; | | | | component4 | typedef utf8str_cs component4; | | |
|
| | | | | | | |
| | | Represents pathname components. | | | | | Represents pathname components. | | |
|
| | | | | | | |
| | linktext4 | typedef opaque linktext4<>; | | | | linktext4 | typedef opaque linktext4<>; | | |
|
| | | | | | | |
| | | Symbolic link contents ("symbolic link" is | | | | | Symbolic link contents ("symbolic link" is | | |
| | | defined in an Open Group [openg_symlink] | | | | | defined in an Open Group [openg_symlink] | | |
| | | standard). | | | | | standard). | | |
|
| | | | | | | |
| | ascii_REQUIRED4 | typedef utf8string ascii_REQUIRED4; | | | | ascii_REQUIRED4 | typedef utf8string ascii_REQUIRED4; | | |
|
| | | | | | | |
| | | String is sent as ASCII and thus is | | | | | String is sent as ASCII and thus is | | |
| | | automatically UTF-8. | | | | | automatically UTF-8. | | |
|
| | | | | | | |
| | pathname4 | typedef component4 pathname4<>; | | | | pathname4 | typedef component4 pathname4<>; | | |
|
| | | Represents path name for fs_locations. | | | | | | | |
| | | | | Represents pathname for fs_locations. | | |
| | | | | | | |
| | nfs_lockid4 | typedef uint64_t nfs_lockid4; | | | | nfs_lockid4 | typedef uint64_t nfs_lockid4; | | |
|
| | | | | | | |
| | verifier4 | typedef opaque verifier4[NFS4_VERIFIER_SIZE]; | | | | verifier4 | typedef opaque verifier4[NFS4_VERIFIER_SIZE]; | | |
|
| | | | | | | |
| | | Verifier used for various operations (COMMIT, | | | | | Verifier used for various operations (COMMIT, | | |
| | | CREATE, OPEN, READDIR, WRITE) | | | | | CREATE, OPEN, READDIR, WRITE) | | |
| | | NFS4_VERIFIER_SIZE is defined as 8. | | | | | NFS4_VERIFIER_SIZE is defined as 8. | | |
| +-----------------+-------------------------------------------------+ | | +-----------------+-------------------------------------------------+ | |
| | | | |
|
| End of Base Data Types | | Table 1: Base NFSv4 Data Types | |
| Table 1 | | | |
| | | | |
| 2.2. Structured Data Types | | 2.2. Structured Data Types | |
| | | | |
| 2.2.1. nfstime4 | | 2.2.1. nfstime4 | |
| | | | |
| struct nfstime4 { | | struct nfstime4 { | |
| int64_t seconds; | | int64_t seconds; | |
| uint32_t nseconds; | | uint32_t nseconds; | |
| }; | | }; | |
| | | | |
| | | | |
| skipping to change at page 20, line 4 | | skipping to change at page 21, line 48 | |
| }; | | }; | |
| | | | |
| 2.2.3. settime4 | | 2.2.3. settime4 | |
| | | | |
| union settime4 switch (time_how4 set_it) { | | union settime4 switch (time_how4 set_it) { | |
| case SET_TO_CLIENT_TIME4: | | case SET_TO_CLIENT_TIME4: | |
| nfstime4 time; | | nfstime4 time; | |
| default: | | default: | |
| void; | | void; | |
| }; | | }; | |
|
| | | | |
| The above definitions are used as the attribute definitions to set | | The above definitions are used as the attribute definitions to set | |
| time values. If set_it is SET_TO_SERVER_TIME4, then the server uses | | time values. If set_it is SET_TO_SERVER_TIME4, then the server uses | |
| its local representation of time for the time value. | | its local representation of time for the time value. | |
| | | | |
| 2.2.4. specdata4 | | 2.2.4. specdata4 | |
| | | | |
| struct specdata4 { | | struct specdata4 { | |
|
| uint32_t specdata1; /* major device number */ | | uint32_t specdata1; /* major device number */ | |
| uint32_t specdata2; /* minor device number */ | | uint32_t specdata2; /* minor device number */ | |
| }; | | }; | |
| | | | |
| This data type represents additional information for the device file | | This data type represents additional information for the device file | |
| types NF4CHR and NF4BLK. | | types NF4CHR and NF4BLK. | |
| | | | |
| 2.2.5. fsid4 | | 2.2.5. fsid4 | |
| | | | |
| struct fsid4 { | | struct fsid4 { | |
| uint64_t major; | | uint64_t major; | |
| uint64_t minor; | | uint64_t minor; | |
| | | | |
| skipping to change at page 20, line 43 | | skipping to change at page 22, line 40 | |
| }; | | }; | |
| | | | |
| 2.2.7. fs_locations4 | | 2.2.7. fs_locations4 | |
| | | | |
| struct fs_locations4 { | | struct fs_locations4 { | |
| pathname4 fs_root; | | pathname4 fs_root; | |
| fs_location4 locations<>; | | fs_location4 locations<>; | |
| }; | | }; | |
| | | | |
| The fs_location4 and fs_locations4 data types are used for the | | The fs_location4 and fs_locations4 data types are used for the | |
|
| fs_locations RECOMMENDED attribute which is used for migration and | | fs_locations RECOMMENDED attribute, which is used for migration and | |
| replication support. | | replication support. | |
| | | | |
| 2.2.8. fattr4 | | 2.2.8. fattr4 | |
| | | | |
| struct fattr4 { | | struct fattr4 { | |
| bitmap4 attrmask; | | bitmap4 attrmask; | |
| attrlist4 attr_vals; | | attrlist4 attr_vals; | |
| }; | | }; | |
|
| | | | |
| The fattr4 structure is used to represent file and directory | | The fattr4 structure is used to represent file and directory | |
| attributes. | | attributes. | |
| | | | |
|
| The bitmap is a counted array of 32 bit integers used to contain bit | | The bitmap is a counted array of 32-bit integers used to contain bit | |
| values. The position of the integer in the array that contains bit n | | values. The position of the integer in the array that contains bit n | |
|
| can be computed from the expression (n / 32) and its bit within that | | can be computed from the expression (n / 32), and its bit within that | |
| integer is (n mod 32). | | integer is (n mod 32). | |
| | | | |
| 0 1 | | 0 1 | |
| +-----------+-----------+-----------+-- | | +-----------+-----------+-----------+-- | |
| | count | 31 .. 0 | 63 .. 32 | | | | count | 31 .. 0 | 63 .. 32 | | |
| +-----------+-----------+-----------+-- | | +-----------+-----------+-----------+-- | |
| | | | |
| 2.2.9. change_info4 | | 2.2.9. change_info4 | |
| | | | |
| struct change_info4 { | | struct change_info4 { | |
| bool atomic; | | bool atomic; | |
| changeid4 before; | | changeid4 before; | |
| changeid4 after; | | changeid4 after; | |
| }; | | }; | |
| | | | |
|
| This structure is used with the CREATE, LINK, REMOVE, RENAME | | This structure is used with the CREATE, LINK, REMOVE, and RENAME | |
| operations to let the client know the value of the change attribute | | operations to let the client know the value of the change attribute | |
| for the directory in which the target file system object resides. | | for the directory in which the target file system object resides. | |
| | | | |
| 2.2.10. clientaddr4 | | 2.2.10. clientaddr4 | |
| | | | |
| struct clientaddr4 { | | struct clientaddr4 { | |
| /* see struct rpcb in RFC 1833 */ | | /* see struct rpcb in RFC 1833 */ | |
| string r_netid<>; /* network id */ | | string r_netid<>; /* network id */ | |
| string r_addr<>; /* universal address */ | | string r_addr<>; /* universal address */ | |
| }; | | }; | |
| | | | |
| The clientaddr4 structure is used as part of the SETCLIENTID | | The clientaddr4 structure is used as part of the SETCLIENTID | |
|
| operation to either specify the address of the client that is using a | | operation, either (1) to specify the address of the client that is | |
| client ID or as part of the callback registration. The r_netid and | | using a client ID or (2) as part of the callback registration. The | |
| r_addr fields respectively contain a network id and universal | | r_netid and r_addr fields respectively contain a network id and | |
| address. The network id and universal address concepts together with | | universal address. The network id and universal address concepts, | |
| formats for TCP over IPv4 and TCP over IPv6 are defined in [RFC5665], | | together with formats for TCP over IPv4 and TCP over IPv6, are | |
| specifically Tables 2 and 3 and Sections 5.2.3.3 and 5.2.3.4. | | defined in [RFC5665], specifically Tables 2 and 3 and | |
| | | Sections 5.2.3.3 and 5.2.3.4. | |
| | | | |
| 2.2.11. cb_client4 | | 2.2.11. cb_client4 | |
| | | | |
| struct cb_client4 { | | struct cb_client4 { | |
| unsigned int cb_program; | | unsigned int cb_program; | |
| clientaddr4 cb_location; | | clientaddr4 cb_location; | |
| }; | | }; | |
|
| This structure is used by the client to inform the server of its call | | | |
| back address; includes the program number and client address. | | This structure is used by the client to inform the server of its | |
| | | callback address; it includes the program number and client address. | |
| | | | |
| 2.2.12. nfs_client_id4 | | 2.2.12. nfs_client_id4 | |
| | | | |
| struct nfs_client_id4 { | | struct nfs_client_id4 { | |
| verifier4 verifier; | | verifier4 verifier; | |
| opaque id<NFS4_OPAQUE_LIMIT>; | | opaque id<NFS4_OPAQUE_LIMIT>; | |
| }; | | }; | |
| | | | |
| This structure is part of the arguments to the SETCLIENTID operation. | | This structure is part of the arguments to the SETCLIENTID operation. | |
| | | | |
| | | | |
| skipping to change at page 23, line 12 | | skipping to change at page 25, line 12 | |
| the confirmation of the lock_owner/lock_seqid pair since it is tied | | the confirmation of the lock_owner/lock_seqid pair since it is tied | |
| to established state in the form of the open_stateid/open_seqid. | | to established state in the form of the open_stateid/open_seqid. | |
| | | | |
| 2.2.16. stateid4 | | 2.2.16. stateid4 | |
| | | | |
| struct stateid4 { | | struct stateid4 { | |
| uint32_t seqid; | | uint32_t seqid; | |
| opaque other[NFS4_OTHER_SIZE]; | | opaque other[NFS4_OTHER_SIZE]; | |
| }; | | }; | |
| | | | |
|
| This structure is used for the various state sharing mechanisms | | This structure is used for the various state-sharing mechanisms | |
| between the client and server. For the client, this data structure | | between the client and server. For the client, this data structure | |
| is read-only. The server is required to increment the seqid field | | is read-only. The server is required to increment the seqid field | |
| monotonically at each transition of the stateid. This is important | | monotonically at each transition of the stateid. This is important | |
| since the client will inspect the seqid in OPEN stateids to determine | | since the client will inspect the seqid in OPEN stateids to determine | |
| the order of OPEN processing done by the server. | | the order of OPEN processing done by the server. | |
| | | | |
| 3. RPC and Security Flavor | | 3. RPC and Security Flavor | |
| | | | |
|
| The NFSv4 protocol is a RPC application that uses RPC version 2 and | | The NFSv4 protocol is an RPC application that uses RPC version 2 and | |
| the XDR as defined in [RFC5531] and [RFC4506]. The RPCSEC_GSS | | the XDR as defined in [RFC5531] and [RFC4506]. The RPCSEC_GSS | |
| security flavors as defined in version 1 ([RFC2203]) and version 2 | | security flavors as defined in version 1 ([RFC2203]) and version 2 | |
| ([RFC5403]) MUST be implemented as the mechanism to deliver stronger | | ([RFC5403]) MUST be implemented as the mechanism to deliver stronger | |
| security for the NFSv4 protocol. However, deployment of RPCSEC_GSS | | security for the NFSv4 protocol. However, deployment of RPCSEC_GSS | |
| is optional. | | is optional. | |
| | | | |
| 3.1. Ports and Transports | | 3.1. Ports and Transports | |
| | | | |
| Historically, NFSv2 and NFSv3 servers have resided on port 2049. The | | Historically, NFSv2 and NFSv3 servers have resided on port 2049. The | |
| registered port 2049 [RFC3232] for the NFS protocol SHOULD be the | | registered port 2049 [RFC3232] for the NFS protocol SHOULD be the | |
| default configuration. Using the registered port for NFS services | | default configuration. Using the registered port for NFS services | |
| means the NFS client will not need to use the RPC binding protocols | | means the NFS client will not need to use the RPC binding protocols | |
| as described in [RFC1833]; this will allow NFS to transit firewalls. | | as described in [RFC1833]; this will allow NFS to transit firewalls. | |
| | | | |
| Where an NFSv4 implementation supports operation over the IP network | | Where an NFSv4 implementation supports operation over the IP network | |
| protocol, the supported transport layer between NFS and IP MUST be an | | protocol, the supported transport layer between NFS and IP MUST be an | |
| IETF standardized transport protocol that is specified to avoid | | IETF standardized transport protocol that is specified to avoid | |
|
| network congestion; such transports include TCP and Stream Control | | network congestion; such transports include TCP and the Stream | |
| Transmission Protocol (SCTP). To enhance the possibilities for | | Control Transmission Protocol (SCTP). To enhance the possibilities | |
| interoperability, an NFSv4 implementation MUST support operation over | | for interoperability, an NFSv4 implementation MUST support operation | |
| the TCP transport protocol. | | over the TCP transport protocol. | |
| | | | |
| If TCP is used as the transport, the client and server SHOULD use | | If TCP is used as the transport, the client and server SHOULD use | |
| persistent connections. This will prevent the weakening of TCP's | | persistent connections. This will prevent the weakening of TCP's | |
|
| congestion control via short lived connections and will improve | | congestion control via short-lived connections and will improve | |
| performance for the Wide Area Network (WAN) environment by | | performance for the Wide Area Network (WAN) environment by | |
| eliminating the need for SYN handshakes. | | eliminating the need for SYN handshakes. | |
| | | | |
|
| As noted in Section 17, the authentication model for NFSv4 has moved | | As noted in Section 19, the authentication model for NFSv4 has moved | |
| from machine-based to principal-based. However, this modification of | | from machine-based to principal-based. However, this modification of | |
| the authentication model does not imply a technical requirement to | | the authentication model does not imply a technical requirement to | |
| move the TCP connection management model from whole machine-based to | | move the TCP connection management model from whole machine-based to | |
|
| one based on a per user model. In particular, NFS over TCP client | | one based on a per-user model. In particular, NFS over TCP client | |
| implementations have traditionally multiplexed traffic for multiple | | implementations have traditionally multiplexed traffic for multiple | |
| users over a common TCP connection between an NFS client and server. | | users over a common TCP connection between an NFS client and server. | |
| This has been true, regardless of whether the NFS client is using | | This has been true, regardless of whether the NFS client is using | |
|
| AUTH_SYS, AUTH_DH, RPCSEC_GSS or any other flavor. Similarly, NFS | | AUTH_SYS, AUTH_DH, RPCSEC_GSS, or any other flavor. Similarly, NFS | |
| over TCP server implementations have assumed such a model and thus | | over TCP server implementations have assumed such a model and thus | |
| scale the implementation of TCP connection management in proportion | | scale the implementation of TCP connection management in proportion | |
| to the number of expected client machines. It is intended that NFSv4 | | to the number of expected client machines. It is intended that NFSv4 | |
| will not modify this connection management model. NFSv4 clients that | | will not modify this connection management model. NFSv4 clients that | |
| violate this assumption can expect scaling issues on the server and | | violate this assumption can expect scaling issues on the server and | |
| hence reduced service. | | hence reduced service. | |
| | | | |
| 3.1.1. Client Retransmission Behavior | | 3.1.1. Client Retransmission Behavior | |
| | | | |
|
| When processing a NFSv4 request received over a reliable transport | | When processing an NFSv4 request received over a reliable transport | |
| such as TCP, the NFSv4 server MUST NOT silently drop the request, | | such as TCP, the NFSv4 server MUST NOT silently drop the request, | |
| except if the established transport connection has been broken. | | except if the established transport connection has been broken. | |
| Given such a contract between NFSv4 clients and servers, clients MUST | | Given such a contract between NFSv4 clients and servers, clients MUST | |
| NOT retry a request unless one or both of the following are true: | | NOT retry a request unless one or both of the following are true: | |
| | | | |
| o The transport connection has been broken | | o The transport connection has been broken | |
| | | | |
| o The procedure being retried is the NULL procedure | | o The procedure being retried is the NULL procedure | |
| | | | |
| Since reliable transports, such as TCP, do not always synchronously | | Since reliable transports, such as TCP, do not always synchronously | |
| inform a peer when the other peer has broken the connection (for | | inform a peer when the other peer has broken the connection (for | |
| example, when an NFS server reboots), the NFSv4 client may want to | | example, when an NFS server reboots), the NFSv4 client may want to | |
| actively "probe" the connection to see if has been broken. Use of | | actively "probe" the connection to see if has been broken. Use of | |
| the NULL procedure is one recommended way to do so. So, when a | | the NULL procedure is one recommended way to do so. So, when a | |
| client experiences a remote procedure call timeout (of some arbitrary | | client experiences a remote procedure call timeout (of some arbitrary | |
|
| implementation specific amount), rather than retrying the remote | | implementation-specific amount), rather than retrying the remote | |
| procedure call, it could instead issue a NULL procedure call to the | | procedure call, it could instead issue a NULL procedure call to the | |
| server. If the server has died, the transport connection break will | | server. If the server has died, the transport connection break will | |
| eventually be indicated to the NFSv4 client. The client can then | | eventually be indicated to the NFSv4 client. The client can then | |
| reconnect, and then retry the original request. If the NULL | | reconnect, and then retry the original request. If the NULL | |
| procedure call gets a response, the connection has not broken. The | | procedure call gets a response, the connection has not broken. The | |
| client can decide to wait longer for the original request's response, | | client can decide to wait longer for the original request's response, | |
|
| or it can break the transport connection and reconnect before re- | | or it can break the transport connection and reconnect before | |
| sending the original request. | | re-sending the original request. | |
| | | | |
| For callbacks from the server to the client, the same rules apply, | | For callbacks from the server to the client, the same rules apply, | |
| but the server doing the callback becomes the client, and the client | | but the server doing the callback becomes the client, and the client | |
| receiving the callback becomes the server. | | receiving the callback becomes the server. | |
| | | | |
| 3.2. Security Flavors | | 3.2. Security Flavors | |
| | | | |
| Traditional RPC implementations have included AUTH_NONE, AUTH_SYS, | | Traditional RPC implementations have included AUTH_NONE, AUTH_SYS, | |
|
| AUTH_DH, and AUTH_KRB4 as security flavors. With [RFC2203] an | | AUTH_DH, and AUTH_KRB4 as security flavors. With [RFC2203], an | |
| additional security flavor of RPCSEC_GSS has been introduced which | | additional security flavor of RPCSEC_GSS has been introduced, which | |
| uses the functionality of GSS-API [RFC2743]. This allows for the use | | uses the functionality of GSS-API [RFC2743]. This allows for the use | |
| of various security mechanisms by the RPC layer without the | | of various security mechanisms by the RPC layer without the | |
| additional implementation overhead of adding RPC security flavors. | | additional implementation overhead of adding RPC security flavors. | |
| For NFSv4, the RPCSEC_GSS security flavor MUST be used to enable the | | For NFSv4, the RPCSEC_GSS security flavor MUST be used to enable the | |
|
| mandatory to implement security mechanism. Other flavors, such as, | | mandatory-to-implement security mechanism. Other flavors, such as | |
| AUTH_NONE, AUTH_SYS, and AUTH_DH MAY be implemented as well. | | AUTH_NONE, AUTH_SYS, and AUTH_DH, MAY be implemented as well. | |
| | | | |
|
| 3.2.1. Security mechanisms for NFSv4 | | 3.2.1. Security Mechanisms for NFSv4 | |
| | | | |
| RPCSEC_GSS, via GSS-API, supports multiple mechanisms that provide | | RPCSEC_GSS, via GSS-API, supports multiple mechanisms that provide | |
| security services. For interoperability, NFSv4 clients and servers | | security services. For interoperability, NFSv4 clients and servers | |
| MUST support the Kerberos V5 security mechanism. | | MUST support the Kerberos V5 security mechanism. | |
| | | | |
| The use of RPCSEC_GSS requires selection of mechanism, quality of | | The use of RPCSEC_GSS requires selection of mechanism, quality of | |
| protection (QOP), and service (authentication, integrity, privacy). | | protection (QOP), and service (authentication, integrity, privacy). | |
| For the mandated security mechanisms, NFSv4 specifies that a QOP of | | For the mandated security mechanisms, NFSv4 specifies that a QOP of | |
| zero is used, leaving it up to the mechanism or the mechanism's | | zero is used, leaving it up to the mechanism or the mechanism's | |
| configuration to map QOP zero to an appropriate level of protection. | | configuration to map QOP zero to an appropriate level of protection. | |
| Each mandated mechanism specifies a minimum set of cryptographic | | Each mandated mechanism specifies a minimum set of cryptographic | |
| algorithms for implementing integrity and privacy. NFSv4 clients and | | algorithms for implementing integrity and privacy. NFSv4 clients and | |
| servers MUST be implemented on operating environments that comply | | servers MUST be implemented on operating environments that comply | |
| with the required cryptographic algorithms of each required | | with the required cryptographic algorithms of each required | |
| mechanism. | | mechanism. | |
| | | | |
| 3.2.1.1. Kerberos V5 as a Security Triple | | 3.2.1.1. Kerberos V5 as a Security Triple | |
| | | | |
| The Kerberos V5 GSS-API mechanism as described in [RFC4121] MUST be | | The Kerberos V5 GSS-API mechanism as described in [RFC4121] MUST be | |
| implemented with the RPCSEC_GSS services as specified in Table 2. | | implemented with the RPCSEC_GSS services as specified in Table 2. | |
|
| Both client and server MUST support each of the pseudo flavors. | | Both client and server MUST support each of the pseudo-flavors. | |
| | | | |
| Mapping pseudo flavor to service | | | |
| | | | |
| +--------+-------+----------------------+-----------------------+ | | +--------+-------+----------------------+-----------------------+ | |
| | Number | Name | Mechanism's OID | RPCSEC_GSS service | | | | Number | Name | Mechanism's OID | RPCSEC_GSS service | | |
| +--------+-------+----------------------+-----------------------+ | | +--------+-------+----------------------+-----------------------+ | |
| | 390003 | krb5 | 1.2.840.113554.1.2.2 | rpc_gss_svc_none | | | | 390003 | krb5 | 1.2.840.113554.1.2.2 | rpc_gss_svc_none | | |
| | 390004 | krb5i | 1.2.840.113554.1.2.2 | rpc_gss_svc_integrity | | | | 390004 | krb5i | 1.2.840.113554.1.2.2 | rpc_gss_svc_integrity | | |
| | 390005 | krb5p | 1.2.840.113554.1.2.2 | rpc_gss_svc_privacy | | | | 390005 | krb5p | 1.2.840.113554.1.2.2 | rpc_gss_svc_privacy | | |
| +--------+-------+----------------------+-----------------------+ | | +--------+-------+----------------------+-----------------------+ | |
| | | | |
|
| Table 2 | | Table 2: Mapping Pseudo-Flavor to Service | |
| | | | |
|
| Note that the pseudo flavor is presented here as a mapping aid to the | | Note that the pseudo-flavor is presented here as a mapping aid to the | |
| implementer. Because this NFS protocol includes a method to | | implementer. Because this NFS protocol includes a method to | |
| negotiate security and it understands the GSS-API mechanism, the | | negotiate security and it understands the GSS-API mechanism, the | |
|
| pseudo flavor is not needed. The pseudo flavor is needed for NFSv3 | | pseudo-flavor is not needed. The pseudo-flavor is needed for NFSv3 | |
| since the security negotiation is done via the MOUNT protocol as | | since the security negotiation is done via the MOUNT protocol as | |
| described in [RFC2623]. | | described in [RFC2623]. | |
| | | | |
| At the time this document was specified, the Advanced Encryption | | At the time this document was specified, the Advanced Encryption | |
| Standard (AES) with HMAC-SHA1 was a required algorithm set for | | Standard (AES) with HMAC-SHA1 was a required algorithm set for | |
| Kerberos V5. In contrast, when NFSv4.0 was first specified in | | Kerberos V5. In contrast, when NFSv4.0 was first specified in | |
| [RFC3530], weaker algorithm sets were REQUIRED for Kerberos V5, and | | [RFC3530], weaker algorithm sets were REQUIRED for Kerberos V5, and | |
| were REQUIRED in the NFSv4.0 specification, because the Kerberos V5 | | were REQUIRED in the NFSv4.0 specification, because the Kerberos V5 | |
| specification at the time did not specify stronger algorithms. The | | specification at the time did not specify stronger algorithms. The | |
| NFSv4 specification does not specify required algorithms for Kerberos | | NFSv4 specification does not specify required algorithms for Kerberos | |
| | | | |
| skipping to change at page 26, line 39 | | skipping to change at page 28, line 35 | |
| or server, so there is some due diligence required by the user of | | or server, so there is some due diligence required by the user of | |
| NFSv4 to ensure that security is acceptable where needed. Guidance | | NFSv4 to ensure that security is acceptable where needed. Guidance | |
| is provided in [RFC6649] as to why weak algorithms should be disabled | | is provided in [RFC6649] as to why weak algorithms should be disabled | |
| by default. | | by default. | |
| | | | |
| 3.3. Security Negotiation | | 3.3. Security Negotiation | |
| | | | |
| With the NFSv4 server potentially offering multiple security | | With the NFSv4 server potentially offering multiple security | |
| mechanisms, the client needs a method to determine or negotiate which | | mechanisms, the client needs a method to determine or negotiate which | |
| mechanism is to be used for its communication with the server. The | | mechanism is to be used for its communication with the server. The | |
|
| NFS server can have multiple points within its file system name space | | NFS server can have multiple points within its file system namespace | |
| that are available for use by NFS clients. In turn the NFS server | | that are available for use by NFS clients. In turn, the NFS server | |
| can be configured such that each of these entry points can have | | can be configured such that each of these entry points can have | |
| different or multiple security mechanisms in use. | | different or multiple security mechanisms in use. | |
| | | | |
| The security negotiation between client and server SHOULD be done | | The security negotiation between client and server SHOULD be done | |
| with a secure channel to eliminate the possibility of a third party | | with a secure channel to eliminate the possibility of a third party | |
| intercepting the negotiation sequence and forcing the client and | | intercepting the negotiation sequence and forcing the client and | |
| server to choose a lower level of security than required or desired. | | server to choose a lower level of security than required or desired. | |
|
| See Section 17 for further discussion. | | See Section 19 for further discussion. | |
| | | | |
| 3.3.1. SECINFO | | 3.3.1. SECINFO | |
| | | | |
|
| The SECINFO operation will allow the client to determine, on a per | | The SECINFO operation will allow the client to determine, on a | |
| filehandle basis, what security triple (see [RFC2743]) is to be used | | per-filehandle basis, what security triple (see [RFC2743] and | |
| for server access. In general, the client will not have to use the | | Section 16.31.4) is to be used for server access. In general, the | |
| SECINFO operation except during initial communication with the server | | client will not have to use the SECINFO operation, except during | |
| or when the client encounters a new security policy as the client | | initial communication with the server or when the client encounters a | |
| navigates the name space. Either condition will force the client to | | new security policy as the client navigates the namespace. Either | |
| negotiate a new security triple. | | condition will force the client to negotiate a new security triple. | |
| | | | |
| 3.3.2. Security Error | | 3.3.2. Security Error | |
| | | | |
| Based on the assumption that each NFSv4 client and server MUST | | Based on the assumption that each NFSv4 client and server MUST | |
|
| support a minimum set of security (i.e., Kerberos-V5 under | | support a minimum set of security (i.e., Kerberos V5 under | |
| RPCSEC_GSS), the NFS client will start its communication with the | | RPCSEC_GSS), the NFS client will start its communication with the | |
| server with one of the minimal security triples. During | | server with one of the minimal security triples. During | |
| communication with the server, the client can receive an NFS error of | | communication with the server, the client can receive an NFS error of | |
| NFS4ERR_WRONGSEC. This error allows the server to notify the client | | NFS4ERR_WRONGSEC. This error allows the server to notify the client | |
| that the security triple currently being used is not appropriate for | | that the security triple currently being used is not appropriate for | |
| access to the server's file system resources. The client is then | | access to the server's file system resources. The client is then | |
| responsible for determining what security triples are available at | | responsible for determining what security triples are available at | |
|
| the server and choose one which is appropriate for the client. See | | the server and choosing one that is appropriate for the client. See | |
| Section 15.33 for further discussion of how the client will respond | | Section 16.31 for further discussion of how the client will respond | |
| to the NFS4ERR_WRONGSEC error and use SECINFO. | | to the NFS4ERR_WRONGSEC error and use SECINFO. | |
| | | | |
| 3.3.3. Callback RPC Authentication | | 3.3.3. Callback RPC Authentication | |
| | | | |
| Except as noted elsewhere in this section, the callback RPC | | Except as noted elsewhere in this section, the callback RPC | |
| (described later) MUST mutually authenticate the NFS server to the | | (described later) MUST mutually authenticate the NFS server to the | |
| principal that acquired the client ID (also described later), using | | principal that acquired the client ID (also described later), using | |
| the security flavor of the original SETCLIENTID operation used. | | the security flavor of the original SETCLIENTID operation used. | |
| | | | |
| For AUTH_NONE, there are no principals, so this is a non-issue. | | For AUTH_NONE, there are no principals, so this is a non-issue. | |
| | | | |
| AUTH_SYS has no notions of mutual authentication or a server | | AUTH_SYS has no notions of mutual authentication or a server | |
| principal, so the callback from the server simply uses the AUTH_SYS | | principal, so the callback from the server simply uses the AUTH_SYS | |
| credential that the user used when he set up the delegation. | | credential that the user used when he set up the delegation. | |
| | | | |
| For AUTH_DH, one commonly used convention is that the server uses the | | For AUTH_DH, one commonly used convention is that the server uses the | |
| credential corresponding to this AUTH_DH principal: | | credential corresponding to this AUTH_DH principal: | |
| | | | |
| unix.host@domain | | unix.host@domain | |
| | | | |
|
| where host and domain are variables corresponding to the name of | | where host and domain are variables corresponding to the name of the | |
| server host and directory services domain in which it lives such as a | | server host and directory services domain in which it lives, such as | |
| Network Information System domain or a DNS domain. | | a Network Information System domain or a DNS domain. | |
| | | | |
| Regardless of what security mechanism under RPCSEC_GSS is being used, | | Regardless of what security mechanism under RPCSEC_GSS is being used, | |
| the NFS server MUST identify itself in GSS-API via a | | the NFS server MUST identify itself in GSS-API via a | |
| GSS_C_NT_HOSTBASED_SERVICE name type. GSS_C_NT_HOSTBASED_SERVICE | | GSS_C_NT_HOSTBASED_SERVICE name type. GSS_C_NT_HOSTBASED_SERVICE | |
| names are of the form: | | names are of the form: | |
| | | | |
| service@hostname | | service@hostname | |
| | | | |
|
| For NFS, the "service" element is | | For NFS, the "service" element is: | |
| | | | |
| nfs | | nfs | |
| | | | |
| Implementations of security mechanisms will convert nfs@hostname to | | Implementations of security mechanisms will convert nfs@hostname to | |
| various different forms. For Kerberos V5, the following form is | | various different forms. For Kerberos V5, the following form is | |
| RECOMMENDED: | | RECOMMENDED: | |
| | | | |
|
| nfs/hostname | | nfs/hostname | |
| | | | |
| For Kerberos V5, nfs/hostname would be a server principal in the | | For Kerberos V5, nfs/hostname would be a server principal in the | |
| Kerberos Key Distribution Center database. This is the same | | Kerberos Key Distribution Center database. This is the same | |
| principal the client acquired a GSS-API context for when it issued | | principal the client acquired a GSS-API context for when it issued | |
|
| the SETCLIENTID operation, therefore, the realm name for the server | | the SETCLIENTID operation; therefore, the realm name for the server | |
| principal must be the same for the callback as it was for the | | principal must be the same for the callback as it was for the | |
| SETCLIENTID. | | SETCLIENTID. | |
| | | | |
| 4. Filehandles | | 4. Filehandles | |
| | | | |
|
| The filehandle in the NFS protocol is a per server unique identifier | | The filehandle in the NFS protocol is a per-server unique identifier | |
| for a file system object. The contents of the filehandle are opaque | | for a file system object. The contents of the filehandle are opaque | |
| to the client. Therefore, the server is responsible for translating | | to the client. Therefore, the server is responsible for translating | |
| the filehandle to an internal representation of the file system | | the filehandle to an internal representation of the file system | |
| object. | | object. | |
| | | | |
| 4.1. Obtaining the First Filehandle | | 4.1. Obtaining the First Filehandle | |
| | | | |
| The operations of the NFS protocol are defined in terms of one or | | The operations of the NFS protocol are defined in terms of one or | |
| more filehandles. Therefore, the client needs a filehandle to | | more filehandles. Therefore, the client needs a filehandle to | |
| initiate communication with the server. With the NFSv2 protocol | | initiate communication with the server. With the NFSv2 protocol | |
| [RFC1094] and the NFSv3 protocol [RFC1813], there exists an ancillary | | [RFC1094] and the NFSv3 protocol [RFC1813], there exists an ancillary | |
| protocol to obtain this first filehandle. The MOUNT protocol, RPC | | protocol to obtain this first filehandle. The MOUNT protocol, RPC | |
|
| program number 100005, provides the mechanism of translating a string | | program number 100005, provides the mechanism of translating a | |
| based file system path name to a filehandle which can then be used by | | string-based file system pathname to a filehandle that can then be | |
| the NFS protocols. | | used by the NFS protocols. | |
| | | | |
| The MOUNT protocol has deficiencies in the area of security and use | | The MOUNT protocol has deficiencies in the area of security and use | |
| via firewalls. This is one reason that the use of the public | | via firewalls. This is one reason that the use of the public | |
| filehandle was introduced in [RFC2054] and [RFC2055]. With the use | | filehandle was introduced in [RFC2054] and [RFC2055]. With the use | |
| of the public filehandle in combination with the LOOKUP operation in | | of the public filehandle in combination with the LOOKUP operation in | |
| the NFSv2 and NFSv3 protocols, it has been demonstrated that the | | the NFSv2 and NFSv3 protocols, it has been demonstrated that the | |
|
| MOUNT protocol is unnecessary for viable interaction between NFS | | MOUNT protocol is unnecessary for viable interaction between the NFS | |
| client and server. | | client and server. | |
| | | | |
| Therefore, the NFSv4 protocol will not use an ancillary protocol for | | Therefore, the NFSv4 protocol will not use an ancillary protocol for | |
|
| translation from string based path names to a filehandle. Two | | translation from string-based pathnames to a filehandle. Two special | |
| special filehandles will be used as starting points for the NFS | | filehandles will be used as starting points for the NFS client. | |
| client. | | | |
| | | | |
| 4.1.1. Root Filehandle | | 4.1.1. Root Filehandle | |
| | | | |
|
| The first of the special filehandles is the ROOT filehandle. The | | The first of the special filehandles is the root filehandle. The | |
| ROOT filehandle is the "conceptual" root of the file system name | | root filehandle is the "conceptual" root of the file system namespace | |
| space at the NFS server. The client uses or starts with the ROOT | | at the NFS server. The client uses or starts with the root | |
| filehandle by employing the PUTROOTFH operation. The PUTROOTFH | | filehandle by employing the PUTROOTFH operation. The PUTROOTFH | |
|
| operation instructs the server to set the "current" filehandle to the | | operation instructs the server to set the current filehandle to the | |
| ROOT of the server's file tree. Once this PUTROOTFH operation is | | root of the server's file tree. Once this PUTROOTFH operation is | |
| used, the client can then traverse the entirety of the server's file | | used, the client can then traverse the entirety of the server's file | |
| tree with the LOOKUP operation. A complete discussion of the server | | tree with the LOOKUP operation. A complete discussion of the server | |
|
| name space is in Section 7. | | namespace is in Section 7. | |
| | | | |
| 4.1.2. Public Filehandle | | 4.1.2. Public Filehandle | |
| | | | |
|
| The second special filehandle is the PUBLIC filehandle. Unlike the | | The second special filehandle is the public filehandle. Unlike the | |
| ROOT filehandle, the PUBLIC filehandle may be bound or represent an | | root filehandle, the public filehandle may be bound or represent an | |
| arbitrary file system object at the server. The server is | | arbitrary file system object at the server. The server is | |
|
| responsible for this binding. It may be that the PUBLIC filehandle | | responsible for this binding. It may be that the public filehandle | |
| and the ROOT filehandle refer to the same file system object. | | and the root filehandle refer to the same file system object. | |
| However, it is up to the administrative software at the server and | | However, it is up to the administrative software at the server and | |
| the policies of the server administrator to define the binding of the | | the policies of the server administrator to define the binding of the | |
|
| PUBLIC filehandle and server file system object. The client may not | | public filehandle and server file system object. The client may not | |
| make any assumptions about this binding. The client uses the PUBLIC | | make any assumptions about this binding. The client uses the public | |
| filehandle via the PUTPUBFH operation. | | filehandle via the PUTPUBFH operation. | |
| | | | |
| 4.2. Filehandle Types | | 4.2. Filehandle Types | |
| | | | |
| In the NFSv2 and NFSv3 protocols, there was one type of filehandle | | In the NFSv2 and NFSv3 protocols, there was one type of filehandle | |
| with a single set of semantics, of which the primary one was that it | | with a single set of semantics, of which the primary one was that it | |
| was persistent across a server reboot. As such, this type of | | was persistent across a server reboot. As such, this type of | |
|
| filehandle is termed "persistent" in NFS Version 4. The semantics of | | filehandle is termed "persistent" in NFSv4. The semantics of a | |
| a persistent filehandle remain the same as before. A new type of | | persistent filehandle remain the same as before. A new type of | |
| filehandle introduced in NFS Version 4 is the "volatile" filehandle, | | filehandle introduced in NFSv4 is the volatile filehandle, which | |
| which attempts to accommodate certain server environments. | | attempts to accommodate certain server environments. | |
| | | | |
| The volatile filehandle type was introduced to address server | | The volatile filehandle type was introduced to address server | |
|
| functionality or implementation issues which make correct | | functionality or implementation issues that make correct | |
| implementation of a persistent filehandle infeasible. Some server | | implementation of a persistent filehandle infeasible. Some server | |
| environments do not provide a file system level invariant that can be | | environments do not provide a file system level invariant that can be | |
| used to construct a persistent filehandle. The underlying server | | used to construct a persistent filehandle. The underlying server | |
|
| file system may not provide the invariant or the server's file system | | file system may not provide the invariant, or the server's file | |
| programming interfaces may not provide access to the needed | | system programming interfaces may not provide access to the needed | |
| invariant. Volatile filehandles may ease the implementation of | | invariant. Volatile filehandles may ease the implementation of | |
|
| server functionality such as hierarchical storage management or file | | server functionality, such as hierarchical storage management or file | |
| system reorganization or migration. However, the volatile filehandle | | system reorganization or migration. However, the volatile filehandle | |
| increases the implementation burden for the client. | | increases the implementation burden for the client. | |
| | | | |
| Since the client will need to handle persistent and volatile | | Since the client will need to handle persistent and volatile | |
|
| filehandles differently, a file attribute is defined which may be | | filehandles differently, a file attribute is defined that may be used | |
| used by the client to determine the filehandle types being returned | | by the client to determine the filehandle types being returned by the | |
| by the server. | | server. | |
| | | | |
| 4.2.1. General Properties of a Filehandle | | 4.2.1. General Properties of a Filehandle | |
| | | | |
| The filehandle contains all the information the server needs to | | The filehandle contains all the information the server needs to | |
| distinguish an individual file. To the client, the filehandle is | | distinguish an individual file. To the client, the filehandle is | |
| opaque. The client stores filehandles for use in a later request and | | opaque. The client stores filehandles for use in a later request and | |
| can compare two filehandles from the same server for equality by | | can compare two filehandles from the same server for equality by | |
| doing a byte-by-byte comparison. However, the client MUST NOT | | doing a byte-by-byte comparison. However, the client MUST NOT | |
| otherwise interpret the contents of filehandles. If two filehandles | | otherwise interpret the contents of filehandles. If two filehandles | |
| from the same server are equal, they MUST refer to the same file. | | from the same server are equal, they MUST refer to the same file. | |
| However, it is not required that two different filehandles refer to | | However, it is not required that two different filehandles refer to | |
|
| different file system objects. Servers SHOULD try to maintain a one- | | different file system objects. Servers SHOULD try to maintain a | |
| to-one correspondence between filehandles and file system objects but | | one-to-one correspondence between filehandles and file system objects | |
| there may be situations in which the mapping is not one-to-one. | | but there may be situations in which the mapping is not one-to-one. | |
| Clients MUST use filehandle comparisons only to improve performance, | | Clients MUST use filehandle comparisons only to improve performance, | |
| not for correct behavior. All clients need to be prepared for | | not for correct behavior. All clients need to be prepared for | |
| situations in which it cannot be determined whether two different | | situations in which it cannot be determined whether two different | |
|
| filehandles denote the same object and in such cases, avoid assuming | | filehandles denote the same object and in such cases need to avoid | |
| that objects denoted are different, as this might cause incorrect | | assuming that objects denoted are different, as this might cause | |
| behavior. Further discussion of filehandle and attribute comparison | | incorrect behavior. Further discussion of filehandle and attribute | |
| in the context of data caching is presented in Section 10.3.4. | | comparison in the context of data caching is presented in | |
| | | Section 10.3.4. | |
| | | | |
|
| As an example, in the case that two different path names when | | As an example, in the case that two different pathnames when | |
| traversed at the server terminate at the same file system object, the | | traversed at the server terminate at the same file system object, the | |
| server SHOULD return the same filehandle for each path. This can | | server SHOULD return the same filehandle for each path. This can | |
|
| occur if a hard link is used to create two file names which refer to | | occur if a hard link is used to create two filenames that refer to | |
| the same underlying file object and associated data. For example, if | | the same underlying file object and associated data. For example, if | |
| paths /a/b/c and /a/d/c refer to the same file, the server SHOULD | | paths /a/b/c and /a/d/c refer to the same file, the server SHOULD | |
|
| return the same filehandle for both path names traversals. | | return the same filehandle for both pathname traversals. | |
| | | | |
| 4.2.2. Persistent Filehandle | | 4.2.2. Persistent Filehandle | |
| | | | |
| A persistent filehandle is defined as having a fixed value for the | | A persistent filehandle is defined as having a fixed value for the | |
| lifetime of the file system object to which it refers. Once the | | lifetime of the file system object to which it refers. Once the | |
| server creates the filehandle for a file system object, the server | | server creates the filehandle for a file system object, the server | |
| MUST accept the same filehandle for the object for the lifetime of | | MUST accept the same filehandle for the object for the lifetime of | |
|
| the object. If the server restarts or reboots the NFS server must | | the object. If the server restarts or reboots, the NFS server must | |
| honor the same filehandle value as it did in the server's previous | | honor the same filehandle value as it did in the server's previous | |
| instantiation. Similarly, if the file system is migrated, the new | | instantiation. Similarly, if the file system is migrated, the new | |
| NFS server must honor the same filehandle as the old NFS server. | | NFS server must honor the same filehandle as the old NFS server. | |
| | | | |
|
| The persistent filehandle will be become stale or invalid when the | | The persistent filehandle will become stale or invalid when the file | |
| file system object is removed. When the server is presented with a | | system object is removed. When the server is presented with a | |
| persistent filehandle that refers to a deleted object, it MUST return | | persistent filehandle that refers to a deleted object, it MUST return | |
| an error of NFS4ERR_STALE. A filehandle may become stale when the | | an error of NFS4ERR_STALE. A filehandle may become stale when the | |
| file system containing the object is no longer available. The file | | file system containing the object is no longer available. The file | |
| system may become unavailable if it exists on removable media and the | | system may become unavailable if it exists on removable media and the | |
|
| media is no longer available at the server or the file system in | | media is no longer available at the server, or if the file system in | |
| whole has been destroyed or the file system has simply been removed | | whole has been destroyed, or if the file system has simply been | |
| from the server's name space (i.e., unmounted in a UNIX environment). | | removed from the server's namespace (i.e., unmounted in a UNIX | |
| | | environment). | |
| | | | |
| 4.2.3. Volatile Filehandle | | 4.2.3. Volatile Filehandle | |
| | | | |
| A volatile filehandle does not share the same longevity | | A volatile filehandle does not share the same longevity | |
| characteristics of a persistent filehandle. The server may determine | | characteristics of a persistent filehandle. The server may determine | |
| that a volatile filehandle is no longer valid at many different | | that a volatile filehandle is no longer valid at many different | |
| points in time. If the server can definitively determine that a | | points in time. If the server can definitively determine that a | |
| volatile filehandle refers to an object that has been removed, the | | volatile filehandle refers to an object that has been removed, the | |
| server should return NFS4ERR_STALE to the client (as is the case for | | server should return NFS4ERR_STALE to the client (as is the case for | |
| persistent filehandles). In all other cases where the server | | persistent filehandles). In all other cases where the server | |
| | | | |
| skipping to change at page 31, line 45 | | skipping to change at page 33, line 47 | |
| FH4_PERSISTENT: The value of FH4_PERSISTENT is used to indicate a | | FH4_PERSISTENT: The value of FH4_PERSISTENT is used to indicate a | |
| persistent filehandle, which is valid until the object is removed | | persistent filehandle, which is valid until the object is removed | |
| from the file system. The server will not return | | from the file system. The server will not return | |
| NFS4ERR_FHEXPIRED for this filehandle. FH4_PERSISTENT is defined | | NFS4ERR_FHEXPIRED for this filehandle. FH4_PERSISTENT is defined | |
| as a value in which none of the bits specified below are set. | | as a value in which none of the bits specified below are set. | |
| | | | |
| FH4_VOLATILE_ANY: The filehandle may expire at any time, except as | | FH4_VOLATILE_ANY: The filehandle may expire at any time, except as | |
| specifically excluded (i.e., FH4_NOEXPIRE_WITH_OPEN). | | specifically excluded (i.e., FH4_NOEXPIRE_WITH_OPEN). | |
| | | | |
| FH4_NOEXPIRE_WITH_OPEN: May only be set when FH4_VOLATILE_ANY is | | FH4_NOEXPIRE_WITH_OPEN: May only be set when FH4_VOLATILE_ANY is | |
|
| set. If this bit is set, then the meaning of FH4_VOLATILE_ANY is | | set. If this bit is set, then the meaning of FH4_VOLATILE_ANY | |
| qualified to exclude any expiration of the filehandle when it is | | is qualified to exclude any expiration of the filehandle when it | |
| open. | | is open. | |
| | | | |
| FH4_VOL_MIGRATION: The filehandle will expire as a result of | | FH4_VOL_MIGRATION: The filehandle will expire as a result of | |
| migration. If FH4_VOLATILE_ANY is set, FH4_VOL_MIGRATION is | | migration. If FH4_VOLATILE_ANY is set, FH4_VOL_MIGRATION is | |
| redundant. | | redundant. | |
| | | | |
| FH4_VOL_RENAME: The filehandle will expire during rename. This | | FH4_VOL_RENAME: The filehandle will expire during rename. This | |
| includes a rename by the requesting client or a rename by any | | includes a rename by the requesting client or a rename by any | |
| other client. If FH4_VOLATILE_ANY is set, FH4_VOL_RENAME is | | other client. If FH4_VOLATILE_ANY is set, FH4_VOL_RENAME is | |
| redundant. | | redundant. | |
| | | | |
|
| Servers which provide volatile filehandles that may expire while open | | Servers that provide volatile filehandles that may expire while open | |
| (i.e., if FH4_VOL_MIGRATION or FH4_VOL_RENAME is set or if | | (i.e., if FH4_VOL_MIGRATION or FH4_VOL_RENAME is set or if | |
|
| FH4_VOLATILE_ANY is set and FH4_NOEXPIRE_WITH_OPEN not set), should | | FH4_VOLATILE_ANY is set and FH4_NOEXPIRE_WITH_OPEN is not set) should | |
| deny a RENAME or REMOVE that would affect an OPEN file of any of the | | deny a RENAME or REMOVE that would affect an OPEN file of any of the | |
| components leading to the OPEN file. In addition, the server SHOULD | | components leading to the OPEN file. In addition, the server SHOULD | |
| deny all RENAME or REMOVE requests during the grace period upon | | deny all RENAME or REMOVE requests during the grace period upon | |
| server restart. | | server restart. | |
| | | | |
| Note that the bits FH4_VOL_MIGRATION and FH4_VOL_RENAME allow the | | Note that the bits FH4_VOL_MIGRATION and FH4_VOL_RENAME allow the | |
| client to determine that expiration has occurred whenever a specific | | client to determine that expiration has occurred whenever a specific | |
| event occurs, without an explicit filehandle expiration error from | | event occurs, without an explicit filehandle expiration error from | |
| the server. FH4_VOLATILE_ANY does not provide this form of | | the server. FH4_VOLATILE_ANY does not provide this form of | |
| information. In situations where the server will expire many, but | | information. In situations where the server will expire many, but | |
|
| not all filehandles upon migration (e.g., all but those that are | | not all, filehandles upon migration (e.g., all but those that are | |
| open), FH4_VOLATILE_ANY (in this case with FH4_NOEXPIRE_WITH_OPEN) is | | open), FH4_VOLATILE_ANY (in this case, with FH4_NOEXPIRE_WITH_OPEN) | |
| a better choice since the client may not assume that all filehandles | | is a better choice since the client may not assume that all | |
| will expire when migration occurs, and it is likely that additional | | filehandles will expire when migration occurs, and it is likely that | |
| expirations will occur (as a result of file CLOSE) that are separated | | additional expirations will occur (as a result of file CLOSE) that | |
| in time from the migration event itself. | | are separated in time from the migration event itself. | |
| | | | |
| 4.2.4. One Method of Constructing a Volatile Filehandle | | 4.2.4. One Method of Constructing a Volatile Filehandle | |
| | | | |
| A volatile filehandle, while opaque to the client, could contain: | | A volatile filehandle, while opaque to the client, could contain: | |
| | | | |
| [volatile bit = 1 | server boot time | slot | generation number] | | [volatile bit = 1 | server boot time | slot | generation number] | |
| | | | |
| o slot is an index in the server volatile filehandle table | | o slot is an index in the server volatile filehandle table | |
| | | | |
|
| o generation number is the generation number for the table entry/ | | o generation number is the generation number for the table | |
| slot | | entry/slot | |
| | | | |
| When the client presents a volatile filehandle, the server makes the | | When the client presents a volatile filehandle, the server makes the | |
| following checks, which assume that the check for the volatile bit | | following checks, which assume that the check for the volatile bit | |
| has passed. If the server boot time is less than the current server | | has passed. If the server boot time is less than the current server | |
| boot time, return NFS4ERR_FHEXPIRED. If slot is out of range, return | | boot time, return NFS4ERR_FHEXPIRED. If slot is out of range, return | |
| NFS4ERR_BADHANDLE. If the generation number does not match, return | | NFS4ERR_BADHANDLE. If the generation number does not match, return | |
| NFS4ERR_FHEXPIRED. | | NFS4ERR_FHEXPIRED. | |
| | | | |
| When the server reboots, the table is gone (it is volatile). | | When the server reboots, the table is gone (it is volatile). | |
| | | | |
|
| If volatile bit is 0, then it is a persistent filehandle with a | | If the volatile bit is 0, then it is a persistent filehandle with a | |
| different structure following it. | | different structure following it. | |
| | | | |
| 4.3. Client Recovery from Filehandle Expiration | | 4.3. Client Recovery from Filehandle Expiration | |
| | | | |
| If possible, the client should recover from the receipt of an | | If possible, the client should recover from the receipt of an | |
| NFS4ERR_FHEXPIRED error. The client must take on additional | | NFS4ERR_FHEXPIRED error. The client must take on additional | |
| responsibility so that it may prepare itself to recover from the | | responsibility so that it may prepare itself to recover from the | |
| expiration of a volatile filehandle. If the server returns | | expiration of a volatile filehandle. If the server returns | |
| persistent filehandles, the client does not need these additional | | persistent filehandles, the client does not need these additional | |
| steps. | | steps. | |
| | | | |
| For volatile filehandles, most commonly the client will need to store | | For volatile filehandles, most commonly the client will need to store | |
| the component names leading up to and including the file system | | the component names leading up to and including the file system | |
| object in question. With these names, the client should be able to | | object in question. With these names, the client should be able to | |
|
| recover by finding a filehandle in the name space that is still | | recover by finding a filehandle in the namespace that is still | |
| available or by starting at the root of the server's file system name | | available or by starting at the root of the server's file system | |
| space. | | namespace. | |
| | | | |
| If the expired filehandle refers to an object that has been removed | | If the expired filehandle refers to an object that has been removed | |
| from the file system, obviously the client will not be able to | | from the file system, obviously the client will not be able to | |
| recover from the expired filehandle. | | recover from the expired filehandle. | |
| | | | |
| It is also possible that the expired filehandle refers to a file that | | It is also possible that the expired filehandle refers to a file that | |
| has been renamed. If the file was renamed by another client, again | | has been renamed. If the file was renamed by another client, again | |
| it is possible that the original client will not be able to recover. | | it is possible that the original client will not be able to recover. | |
| However, in the case that the client itself is renaming the file and | | However, in the case that the client itself is renaming the file and | |
| the file is open, it is possible that the client may be able to | | the file is open, it is possible that the client may be able to | |
|
| recover. The client can determine the new path name based on the | | recover. The client can determine the new pathname based on the | |
| processing of the rename request. The client can then regenerate the | | processing of the rename request. The client can then regenerate the | |
|
| new filehandle based on the new path name. The client could also use | | new filehandle based on the new pathname. The client could also use | |
| the compound operation mechanism to construct a set of operations | | the COMPOUND operation mechanism to construct a set of operations | |
| like: | | like: | |
| | | | |
| RENAME A B | | RENAME A B | |
| LOOKUP B | | LOOKUP B | |
| GETFH | | GETFH | |
| | | | |
| Note that the COMPOUND procedure does not provide atomicity. This | | Note that the COMPOUND procedure does not provide atomicity. This | |
| example only reduces the overhead of recovering from an expired | | example only reduces the overhead of recovering from an expired | |
| filehandle. | | filehandle. | |
| | | | |
| 5. Attributes | | 5. Attributes | |
| | | | |
| To meet the requirements of extensibility and increased | | To meet the requirements of extensibility and increased | |
| interoperability with non-UNIX platforms, attributes need to be | | interoperability with non-UNIX platforms, attributes need to be | |
| handled in a flexible manner. The NFSv3 fattr3 structure contains a | | handled in a flexible manner. The NFSv3 fattr3 structure contains a | |
| fixed list of attributes that not all clients and servers are able to | | fixed list of attributes that not all clients and servers are able to | |
| support or care about. The fattr3 structure cannot be extended as | | support or care about. The fattr3 structure cannot be extended as | |
|
| new needs arise and it provides no way to indicate non-support. With | | new needs arise, and it provides no way to indicate non-support. | |
| the NFSv4.0 protocol, the client is able to query what attributes the | | With the NFSv4.0 protocol, the client is able to query what | |
| server supports and construct requests with only those supported | | attributes the server supports and construct requests with only those | |
| attributes (or a subset thereof). | | supported attributes (or a subset thereof). | |
| | | | |
| To this end, attributes are divided into three groups: REQUIRED, | | To this end, attributes are divided into three groups: REQUIRED, | |
| RECOMMENDED, and named. Both REQUIRED and RECOMMENDED attributes are | | RECOMMENDED, and named. Both REQUIRED and RECOMMENDED attributes are | |
| supported in the NFSv4.0 protocol by a specific and well-defined | | supported in the NFSv4.0 protocol by a specific and well-defined | |
| encoding and are identified by number. They are requested by setting | | encoding and are identified by number. They are requested by setting | |
| a bit in the bit vector sent in the GETATTR request; the server | | a bit in the bit vector sent in the GETATTR request; the server | |
| response includes a bit vector to list what attributes were returned | | response includes a bit vector to list what attributes were returned | |
| in the response. New REQUIRED or RECOMMENDED attributes may be added | | in the response. New REQUIRED or RECOMMENDED attributes may be added | |
| to the NFSv4 protocol as part of a new minor version by publishing a | | to the NFSv4 protocol as part of a new minor version by publishing a | |
|
| Standards Track RFC which allocates a new attribute number value and | | Standards Track RFC that allocates a new attribute number value and | |
| defines the encoding for the attribute. See Section 11 for further | | defines the encoding for the attribute. See Section 11 for further | |
| discussion. | | discussion. | |
| | | | |
| Named attributes are accessed by the OPENATTR operation, which | | Named attributes are accessed by the OPENATTR operation, which | |
| accesses a hidden directory of attributes associated with a file | | accesses a hidden directory of attributes associated with a file | |
| system object. OPENATTR takes a filehandle for the object and | | system object. OPENATTR takes a filehandle for the object and | |
| returns the filehandle for the attribute hierarchy. The filehandle | | returns the filehandle for the attribute hierarchy. The filehandle | |
| for the named attributes is a directory object accessible by LOOKUP | | for the named attributes is a directory object accessible by LOOKUP | |
| or READDIR and contains files whose names represent the named | | or READDIR and contains files whose names represent the named | |
| attributes and whose data bytes are the value of the attribute. For | | attributes and whose data bytes are the value of the attribute. For | |
| | | | |
| skipping to change at page 34, line 44 | | skipping to change at page 36, line 47 | |
| +----------+-----------+---------------------------------+ | | +----------+-----------+---------------------------------+ | |
| | | | |
| Named attributes are intended for data needed by applications rather | | Named attributes are intended for data needed by applications rather | |
| than by an NFS client implementation. NFS implementers are strongly | | than by an NFS client implementation. NFS implementers are strongly | |
| encouraged to define their new attributes as RECOMMENDED attributes | | encouraged to define their new attributes as RECOMMENDED attributes | |
| by bringing them to the IETF Standards Track process. | | by bringing them to the IETF Standards Track process. | |
| | | | |
| The set of attributes that are classified as REQUIRED is deliberately | | The set of attributes that are classified as REQUIRED is deliberately | |
| small since servers need to do whatever it takes to support them. A | | small since servers need to do whatever it takes to support them. A | |
| server should support as many of the RECOMMENDED attributes as | | server should support as many of the RECOMMENDED attributes as | |
|
| possible but, by their definition, the server is not required to | | possible; however, by their definition, the server is not required to | |
| support all of them. Attributes are deemed REQUIRED if the data is | | support all of them. Attributes are deemed REQUIRED if the data is | |
| both needed by a large number of clients and is not otherwise | | both needed by a large number of clients and is not otherwise | |
| reasonably computable by the client when support is not provided on | | reasonably computable by the client when support is not provided on | |
| the server. | | the server. | |
| | | | |
| Note that the hidden directory returned by OPENATTR is a convenience | | Note that the hidden directory returned by OPENATTR is a convenience | |
| for protocol processing. The client should not make any assumptions | | for protocol processing. The client should not make any assumptions | |
| about the server's implementation of named attributes and whether or | | about the server's implementation of named attributes and whether or | |
| not the underlying file system at the server has a named attribute | | not the underlying file system at the server has a named attribute | |
| directory. Therefore, operations such as SETATTR and GETATTR on the | | directory. Therefore, operations such as SETATTR and GETATTR on the | |
| named attribute directory are undefined. | | named attribute directory are undefined. | |
| | | | |
| 5.1. REQUIRED Attributes | | 5.1. REQUIRED Attributes | |
| | | | |
|
| These MUST be supported by every NFSv4.0 client and server in order | | These attributes MUST be supported by every NFSv4.0 client and server | |
| to ensure a minimum level of interoperability. The server MUST store | | in order to ensure a minimum level of interoperability. The server | |
| and return these attributes, and the client MUST be able to function | | MUST store and return these attributes, and the client MUST be able | |
| with an attribute set limited to these attributes. With just the | | to function with an attribute set limited to these attributes. With | |
| REQUIRED attributes some client functionality can be impaired or | | just the REQUIRED attributes, some client functionality can be | |
| limited in some ways. A client can ask for any of these attributes | | impaired or limited in some ways. A client can ask for any of these | |
| to be returned by setting a bit in the GETATTR request. For each | | attributes to be returned by setting a bit in the GETATTR request. | |
| such bit set, the server MUST return the corresponding attribute | | For each such bit set, the server MUST return the corresponding | |
| value. | | attribute value. | |
| | | | |
| 5.2. RECOMMENDED Attributes | | 5.2. RECOMMENDED Attributes | |
| | | | |
| These attributes are understood well enough to warrant support in the | | These attributes are understood well enough to warrant support in the | |
| NFSv4.0 protocol. However, they may not be supported on all clients | | NFSv4.0 protocol. However, they may not be supported on all clients | |
| and servers. A client MAY ask for any of these attributes to be | | and servers. A client MAY ask for any of these attributes to be | |
| returned by setting a bit in the GETATTR request but MUST handle the | | returned by setting a bit in the GETATTR request but MUST handle the | |
| case where the server does not return them. A client MAY ask for the | | case where the server does not return them. A client MAY ask for the | |
| set of attributes the server supports and SHOULD NOT request | | set of attributes the server supports and SHOULD NOT request | |
| attributes the server does not support. A server should be tolerant | | attributes the server does not support. A server should be tolerant | |
|
| of requests for unsupported attributes and simply not return them | | of requests for unsupported attributes and simply not return them, | |
| rather than considering the request an error. It is expected that | | rather than considering the request an error. It is expected that | |
| servers will support all attributes they comfortably can and only | | servers will support all attributes they comfortably can and only | |
| fail to support attributes that are difficult to support in their | | fail to support attributes that are difficult to support in their | |
| operating environments. A server should provide attributes whenever | | operating environments. A server should provide attributes whenever | |
| they don't have to "tell lies" to the client. For example, a file | | they don't have to "tell lies" to the client. For example, a file | |
|
| modification time should be either an accurate time or should not be | | modification time either should be an accurate time or should not be | |
| supported by the server. At times this will be difficult for | | supported by the server. At times this will be difficult for | |
| clients, but a client is better positioned to decide whether and how | | clients, but a client is better positioned to decide whether and how | |
| to fabricate or construct an attribute or whether to do without the | | to fabricate or construct an attribute or whether to do without the | |
| attribute. | | attribute. | |
| | | | |
| 5.3. Named Attributes | | 5.3. Named Attributes | |
| | | | |
| These attributes are not supported by direct encoding in the NFSv4 | | These attributes are not supported by direct encoding in the NFSv4 | |
| protocol but are accessed by string names rather than numbers and | | protocol but are accessed by string names rather than numbers and | |
| correspond to an uninterpreted stream of bytes that are stored with | | correspond to an uninterpreted stream of bytes that are stored with | |
|
| the file system object. The name space for these attributes may be | | the file system object. The namespace for these attributes may be | |
| accessed by using the OPENATTR operation. The OPENATTR operation | | accessed by using the OPENATTR operation. The OPENATTR operation | |
| returns a filehandle for a virtual "named attribute directory", and | | returns a filehandle for a virtual "named attribute directory", and | |
|
| further perusal and modification of the name space may be done using | | further perusal and modification of the namespace may be done using | |
| operations that work on more typical directories. In particular, | | operations that work on more typical directories. In particular, | |
| READDIR may be used to get a list of such named attributes, and | | READDIR may be used to get a list of such named attributes, and | |
| LOOKUP and OPEN may select a particular attribute. Creation of a new | | LOOKUP and OPEN may select a particular attribute. Creation of a new | |
| named attribute may be the result of an OPEN specifying file | | named attribute may be the result of an OPEN specifying file | |
| creation. | | creation. | |
| | | | |
| Once an OPEN is done, named attributes may be examined and changed by | | Once an OPEN is done, named attributes may be examined and changed by | |
| normal READ and WRITE operations using the filehandles and stateids | | normal READ and WRITE operations using the filehandles and stateids | |
| returned by OPEN. | | returned by OPEN. | |
| | | | |
| | | | |
| skipping to change at page 36, line 24 | | skipping to change at page 38, line 26 | |
| (non-named) attributes. Each of these objects must have all of the | | (non-named) attributes. Each of these objects must have all of the | |
| REQUIRED attributes and may have additional RECOMMENDED attributes. | | REQUIRED attributes and may have additional RECOMMENDED attributes. | |
| However, the set of attributes for named attributes and the named | | However, the set of attributes for named attributes and the named | |
| attribute directory need not be, and typically will not be, as large | | attribute directory need not be, and typically will not be, as large | |
| as that for other objects in that file system. | | as that for other objects in that file system. | |
| | | | |
| Named attributes might be the target of delegations. However, since | | Named attributes might be the target of delegations. However, since | |
| granting of delegations is at the server's discretion, a server need | | granting of delegations is at the server's discretion, a server need | |
| not support delegations on named attributes. | | not support delegations on named attributes. | |
| | | | |
|
| It is RECOMMENDED that servers support arbitrary named attributes. A | | It is RECOMMENDED that servers support arbitrary named attributes. | |
| client should not depend on the ability to store any named attributes | | A client should not depend on the ability to store any named | |
| in the server's file system. If a server does support named | | attributes in the server's file system. If a server does support | |
| attributes, a client that is also able to handle them should be able | | named attributes, a client that is also able to handle them should be | |
| to copy a file's data and metadata with complete transparency from | | able to copy a file's data and metadata with complete transparency | |
| one location to another; this would imply that names allowed for | | from one location to another; this would imply that names allowed for | |
| regular directory entries are valid for named attribute names as | | regular directory entries are valid for named attribute names | |
| well. | | as well. | |
| | | | |
| In NFSv4.0, the structure of named attribute directories is | | In NFSv4.0, the structure of named attribute directories is | |
| restricted in a number of ways, in order to prevent the development | | restricted in a number of ways, in order to prevent the development | |
| of non-interoperable implementations in which some servers support a | | of non-interoperable implementations in which some servers support a | |
| fully general hierarchical directory structure for named attributes | | fully general hierarchical directory structure for named attributes | |
| while others support a limited but adequate structure for named | | while others support a limited but adequate structure for named | |
| attributes. In such an environment, clients or applications might | | attributes. In such an environment, clients or applications might | |
| come to depend on non-portable extensions. The restrictions are: | | come to depend on non-portable extensions. The restrictions are: | |
| | | | |
| o CREATE is not allowed in a named attribute directory. Thus, such | | o CREATE is not allowed in a named attribute directory. Thus, such | |
| | | | |
| skipping to change at page 37, line 14 | | skipping to change at page 39, line 14 | |
| | | | |
| o Doing a RENAME of a named attribute to a different named attribute | | o Doing a RENAME of a named attribute to a different named attribute | |
| directory or to an ordinary (i.e., non-named-attribute) directory | | directory or to an ordinary (i.e., non-named-attribute) directory | |
| is not allowed. | | is not allowed. | |
| | | | |
| o Creating hard links between named attribute directories or between | | o Creating hard links between named attribute directories or between | |
| named attribute directories and ordinary directories is not | | named attribute directories and ordinary directories is not | |
| allowed. | | allowed. | |
| | | | |
| Names of attributes will not be controlled by this document or other | | Names of attributes will not be controlled by this document or other | |
|
| IETF Standards Track documents. See Section 18 for further | | IETF Standards Track documents. See Section 20 for further | |
| discussion. | | discussion. | |
| | | | |
| 5.4. Classification of Attributes | | 5.4. Classification of Attributes | |
| | | | |
|
| Each of attributes accessed using SETATTR and GETATTR (i.e., REQUIRED | | Each of the attributes accessed using SETATTR and GETATTR (i.e., | |
| an RECOMMENDED attributes) can be classified in one of three | | REQUIRED and RECOMMENDED attributes) can be classified in one of | |
| categories: | | three categories: | |
| | | | |
|
| 1. per server attributes for which the value of the attribute will | | 1. per-server attributes for which the value of the attribute will | |
| be the same for all file objects that share the same server. | | be the same for all file objects that share the same server. | |
| | | | |
|
| 2. per file system attributes for which the value of the attribute | | 2. per-file system attributes for which the value of the attribute | |
| will be the same for some or all file objects that share the same | | will be the same for some or all file objects that share the same | |
| server and fsid attribute (Section 5.8.1.9). See below for | | server and fsid attribute (Section 5.8.1.9). See below for | |
| details regarding when such sharing is in effect. | | details regarding when such sharing is in effect. | |
| | | | |
|
| 3. per file system object attributes | | 3. per-file system object attributes. | |
| | | | |
|
| The handling of per file system attributes depends on the particular | | The handling of per-file system attributes depends on the particular | |
| attribute and the setting of the homogeneous (Section 5.8.2.12) | | attribute and the setting of the homogeneous (Section 5.8.2.12) | |
| attribute. The following rules apply: | | attribute. The following rules apply: | |
| | | | |
|
| 1. The values of the attribute supported_attrs, fsid, homogeneous, | | 1. The values of the attributes supported_attrs, fsid, homogeneous, | |
| link_support, and symlink_support are always common to all object | | link_support, and symlink_support are always common to all | |
| within the given file system. | | objects within the given file system. | |
| | | | |
| 2. For other attributes, different values may be returned for | | 2. For other attributes, different values may be returned for | |
| different file system objects if the attribute homogeneous is | | different file system objects if the attribute homogeneous is | |
| supported within the file system in question and has the value | | supported within the file system in question and has the value | |
| false. | | false. | |
| | | | |
| The classification of attributes is as follows. Note that the | | The classification of attributes is as follows. Note that the | |
| attributes time_access_set and time_modify_set are not listed in this | | attributes time_access_set and time_modify_set are not listed in this | |
|
| section because they are write-only attributes corresponding to | | section, because they are write-only attributes corresponding to | |
| time_access and time_modify, and are used in a special instance of | | time_access and time_modify and are used in a special instance of | |
| SETATTR. | | SETATTR. | |
| | | | |
| o The per-server attribute is: | | o The per-server attribute is: | |
| | | | |
| lease_time | | lease_time | |
| | | | |
| o The per-file system attributes are: | | o The per-file system attributes are: | |
| | | | |
| supported_attrs, fh_expire_type, link_support, symlink_support, | | supported_attrs, fh_expire_type, link_support, symlink_support, | |
| unique_handles, aclsupport, cansettime, case_insensitive, | | unique_handles, aclsupport, cansettime, case_insensitive, | |
| case_preserving, chown_restricted, files_avail, files_free, | | case_preserving, chown_restricted, files_avail, files_free, | |
| files_total, fs_locations, homogeneous, maxfilesize, maxname, | | files_total, fs_locations, homogeneous, maxfilesize, maxname, | |
| maxread, maxwrite, no_trunc, space_avail, space_free, | | maxread, maxwrite, no_trunc, space_avail, space_free, | |
|
| space_total, time_delta, | | space_total, and time_delta | |
| | | | |
| o The per-file system object attributes are: | | o The per-file system object attributes are: | |
| | | | |
| type, change, size, named_attr, fsid, rdattr_error, filehandle, | | type, change, size, named_attr, fsid, rdattr_error, filehandle, | |
| acl, archive, fileid, hidden, maxlink, mimetype, mode, | | acl, archive, fileid, hidden, maxlink, mimetype, mode, | |
| numlinks, owner, owner_group, rawdev, space_used, system, | | numlinks, owner, owner_group, rawdev, space_used, system, | |
| time_access, time_backup, time_create, time_metadata, | | time_access, time_backup, time_create, time_metadata, | |
|
| time_modify, mounted_on_fileid | | time_modify, and mounted_on_fileid | |
| | | | |
| For quota_avail_hard, quota_avail_soft, and quota_used, see their | | For quota_avail_hard, quota_avail_soft, and quota_used, see their | |
| definitions below for the appropriate classification. | | definitions below for the appropriate classification. | |
| | | | |
| 5.5. Set-Only and Get-Only Attributes | | 5.5. Set-Only and Get-Only Attributes | |
| | | | |
| Some REQUIRED and RECOMMENDED attributes are set-only; i.e., they can | | Some REQUIRED and RECOMMENDED attributes are set-only; i.e., they can | |
| be set via SETATTR but not retrieved via GETATTR. Similarly, some | | be set via SETATTR but not retrieved via GETATTR. Similarly, some | |
| REQUIRED and RECOMMENDED attributes are get-only; i.e., they can be | | REQUIRED and RECOMMENDED attributes are get-only; i.e., they can be | |
| retrieved via GETATTR but not set via SETATTR. If a client attempts | | retrieved via GETATTR but not set via SETATTR. If a client attempts | |
| to set a get-only attribute or get a set-only attribute, the server | | to set a get-only attribute or get a set-only attribute, the server | |
| MUST return NFS4ERR_INVAL. | | MUST return NFS4ERR_INVAL. | |
| | | | |
| 5.6. REQUIRED Attributes - List and Definition References | | 5.6. REQUIRED Attributes - List and Definition References | |
| | | | |
|
| The list of REQUIRED attributes appears in Table 3. The meaning of | | The list of REQUIRED attributes appears in Table 3. The meanings of | |
| the columns of the table are: | | the columns of the table are: | |
| | | | |
|
| o Name: The name of attribute | | o Name: The name of the attribute. | |
| | | | |
|
| o Id: The number assigned to the attribute. In the event of | | o ID: The number assigned to the attribute. In the event of | |
| conflicts between the assigned number and [RFCNFSv4XDR], the | | conflicts between the assigned number and [RFC7531], the latter is | |
| latter is authoritative, but in such an event, it should be | | authoritative, but in such an event, it should be resolved with | |
| resolved with Errata to this document and/or [RFCNFSv4XDR]. See | | errata to this document and/or [RFC7531]. See [IESG_ERRATA] for | |
| [IESG_ERRATA] for the Errata process. | | the errata process. | |
| | | | |
| o Data Type: The XDR data type of the attribute. | | o Data Type: The XDR data type of the attribute. | |
| | | | |
| o Acc: Access allowed to the attribute. R means read-only (GETATTR | | o Acc: Access allowed to the attribute. R means read-only (GETATTR | |
| may retrieve, SETATTR may not set). W means write-only (SETATTR | | may retrieve, SETATTR may not set). W means write-only (SETATTR | |
| may set, GETATTR may not retrieve). R W means read/write (GETATTR | | may set, GETATTR may not retrieve). R W means read/write (GETATTR | |
| may retrieve, SETATTR may set). | | may retrieve, SETATTR may set). | |
| | | | |
| o Defined in: The section of this specification that describes the | | o Defined in: The section of this specification that describes the | |
| attribute. | | attribute. | |
| | | | |
|
| REQUIRED attributes | | | |
| | | | |
| +-----------------+----+------------+-----+-------------------+ | | +-----------------+----+------------+-----+-------------------+ | |
|
| | Name | Id | Data Type | Acc | Defined in: | | | | Name | ID | Data Type | Acc | Defined in | | |
| +-----------------+----+------------+-----+-------------------+ | | +-----------------+----+------------+-----+-------------------+ | |
| | supported_attrs | 0 | bitmap4 | R | Section 5.8.1.1 | | | | supported_attrs | 0 | bitmap4 | R | Section 5.8.1.1 | | |
| | type | 1 | nfs_ftype4 | R | Section 5.8.1.2 | | | | type | 1 | nfs_ftype4 | R | Section 5.8.1.2 | | |
| | fh_expire_type | 2 | uint32_t | R | Section 5.8.1.3 | | | | fh_expire_type | 2 | uint32_t | R | Section 5.8.1.3 | | |
| | change | 3 | changeid4 | R | Section 5.8.1.4 | | | | change | 3 | changeid4 | R | Section 5.8.1.4 | | |
| | size | 4 | uint64_t | R W | Section 5.8.1.5 | | | | size | 4 | uint64_t | R W | Section 5.8.1.5 | | |
| | link_support | 5 | bool | R | Section 5.8.1.6 | | | | link_support | 5 | bool | R | Section 5.8.1.6 | | |
| | symlink_support | 6 | bool | R | Section 5.8.1.7 | | | | symlink_support | 6 | bool | R | Section 5.8.1.7 | | |
| | named_attr | 7 | bool | R | Section 5.8.1.8 | | | | named_attr | 7 | bool | R | Section 5.8.1.8 | | |
| | fsid | 8 | fsid4 | R | Section 5.8.1.9 | | | | fsid | 8 | fsid4 | R | Section 5.8.1.9 | | |
| | unique_handles | 9 | bool | R | Section 5.8.1.10 | | | | unique_handles | 9 | bool | R | Section 5.8.1.10 | | |
| | lease_time | 10 | nfs_lease4 | R | Section 5.8.1.11 | | | | lease_time | 10 | nfs_lease4 | R | Section 5.8.1.11 | | |
| | rdattr_error | 11 | nfsstat4 | R | Section 5.8.1.12 | | | | rdattr_error | 11 | nfsstat4 | R | Section 5.8.1.12 | | |
| | filehandle | 19 | nfs_fh4 | R | Section 5.8.1.13 | | | | filehandle | 19 | nfs_fh4 | R | Section 5.8.1.13 | | |
| +-----------------+----+------------+-----+-------------------+ | | +-----------------+----+------------+-----+-------------------+ | |
| | | | |
|
| Table 3 | | Table 3: REQUIRED Attributes | |
| | | | |
| 5.7. RECOMMENDED Attributes - List and Definition References | | 5.7. RECOMMENDED Attributes - List and Definition References | |
| | | | |
| The RECOMMENDED attributes are defined in Table 4. The meanings of | | The RECOMMENDED attributes are defined in Table 4. The meanings of | |
| the column headers are the same as Table 3; see Section 5.6 for the | | the column headers are the same as Table 3; see Section 5.6 for the | |
| meanings. | | meanings. | |
| | | | |
|
| RECOMMENDED attributes | | | |
| | | | |
| +-------------------+----+-----------------+-----+------------------+ | | +-------------------+----+-----------------+-----+------------------+ | |
|
| | Name | Id | Data Type | Acc | Defined in: | | | | Name | ID | Data Type | Acc | Defined in | | |
| +-------------------+----+-----------------+-----+------------------+ | | +-------------------+----+-----------------+-----+------------------+ | |
| | acl | 12 | nfsace4<> | R W | Section 6.2.1 | | | | acl | 12 | nfsace4<> | R W | Section 6.2.1 | | |
| | aclsupport | 13 | uint32_t | R | Section 6.2.1.2 | | | | aclsupport | 13 | uint32_t | R | Section 6.2.1.2 | | |
| | archive | 14 | bool | R W | Section 5.8.2.1 | | | | archive | 14 | bool | R W | Section 5.8.2.1 | | |
| | cansettime | 15 | bool | R | Section 5.8.2.2 | | | | cansettime | 15 | bool | R | Section 5.8.2.2 | | |
| | case_insensitive | 16 | bool | R | Section 5.8.2.3 | | | | case_insensitive | 16 | bool | R | Section 5.8.2.3 | | |
| | case_preserving | 17 | bool | R | Section 5.8.2.4 | | | | case_preserving | 17 | bool | R | Section 5.8.2.4 | | |
| | chown_restricted | 18 | bool | R | Section 5.8.2.5 | | | | chown_restricted | 18 | bool | R | Section 5.8.2.5 | | |
| | fileid | 20 | uint64_t | R | Section 5.8.2.6 | | | | fileid | 20 | uint64_t | R | Section 5.8.2.6 | | |
| | files_avail | 21 | uint64_t | R | Section 5.8.2.7 | | | | files_avail | 21 | uint64_t | R | Section 5.8.2.7 | | |
| | | | |
| skipping to change at page 40, line 28 | | skipping to change at page 42, line 13 | |
| | files_total | 23 | uint64_t | R | Section 5.8.2.9 | | | | files_total | 23 | uint64_t | R | Section 5.8.2.9 | | |
| | fs_locations | 24 | fs_locations4 | R | Section 5.8.2.10 | | | | fs_locations | 24 | fs_locations4 | R | Section 5.8.2.10 | | |
| | hidden | 25 | bool | R W | Section 5.8.2.11 | | | | hidden | 25 | bool | R W | Section 5.8.2.11 | | |
| | homogeneous | 26 | bool | R | Section 5.8.2.12 | | | | homogeneous | 26 | bool | R | Section 5.8.2.12 | | |
| | maxfilesize | 27 | uint64_t | R | Section 5.8.2.13 | | | | maxfilesize | 27 | uint64_t | R | Section 5.8.2.13 | | |
| | maxlink | 28 | uint32_t | R | Section 5.8.2.14 | | | | maxlink | 28 | uint32_t | R | Section 5.8.2.14 | | |
| | maxname | 29 | uint32_t | R | Section 5.8.2.15 | | | | maxname | 29 | uint32_t | R | Section 5.8.2.15 | | |
| | maxread | 30 | uint64_t | R | Section 5.8.2.16 | | | | maxread | 30 | uint64_t | R | Section 5.8.2.16 | | |
| | maxwrite | 31 | uint64_t | R | Section 5.8.2.17 | | | | maxwrite | 31 | uint64_t | R | Section 5.8.2.17 | | |
| | mimetype | 32 | ascii_ | R W | Section 5.8.2.18 | | | | mimetype | 32 | ascii_ | R W | Section 5.8.2.18 | | |
|
| | | | REQUIRED4<> | | | | | | | | REQUIRED4<> | | | | |
| | mode | 33 | mode4 | R W | Section 6.2.2 | | | | mode | 33 | mode4 | R W | Section 6.2.2 | | |
| | mounted_on_fileid | 55 | uint64_t | R | Section 5.8.2.19 | | | | mounted_on_fileid | 55 | uint64_t | R | Section 5.8.2.19 | | |
| | no_trunc | 34 | bool | R | Section 5.8.2.20 | | | | no_trunc | 34 | bool | R | Section 5.8.2.20 | | |
| | numlinks | 35 | uint32_t | R | Section 5.8.2.21 | | | | numlinks | 35 | uint32_t | R | Section 5.8.2.21 | | |
| | owner | 36 | utf8str_mixed | R W | Section 5.8.2.22 | | | | owner | 36 | utf8str_mixed | R W | Section 5.8.2.22 | | |
| | owner_group | 37 | utf8str_mixed | R W | Section 5.8.2.23 | | | | owner_group | 37 | utf8str_mixed | R W | Section 5.8.2.23 | | |
| | quota_avail_hard | 38 | uint64_t | R | Section 5.8.2.24 | | | | quota_avail_hard | 38 | uint64_t | R | Section 5.8.2.24 | | |
| | quota_avail_soft | 39 | uint64_t | R | Section 5.8.2.25 | | | | quota_avail_soft | 39 | uint64_t | R | Section 5.8.2.25 | | |
| | quota_used | 40 | uint64_t | R | Section 5.8.2.26 | | | | quota_used | 40 | uint64_t | R | Section 5.8.2.26 | | |
| | rawdev | 41 | specdata4 | R | Section 5.8.2.27 | | | | rawdev | 41 | specdata4 | R | Section 5.8.2.27 | | |
| | | | |
| skipping to change at page 41, line 4 | | skipping to change at page 42, line 38 | |
| | system | 46 | bool | R W | Section 5.8.2.32 | | | | system | 46 | bool | R W | Section 5.8.2.32 | | |
| | time_access | 47 | nfstime4 | R | Section 5.8.2.33 | | | | time_access | 47 | nfstime4 | R | Section 5.8.2.33 | | |
| | time_access_set | 48 | settime4 | W | Section 5.8.2.34 | | | | time_access_set | 48 | settime4 | W | Section 5.8.2.34 | | |
| | time_backup | 49 | nfstime4 | R W | Section 5.8.2.35 | | | | time_backup | 49 | nfstime4 | R W | Section 5.8.2.35 | | |
| | time_create | 50 | nfstime4 | R W | Section 5.8.2.36 | | | | time_create | 50 | nfstime4 | R W | Section 5.8.2.36 | | |
| | time_delta | 51 | nfstime4 | R | Section 5.8.2.37 | | | | time_delta | 51 | nfstime4 | R | Section 5.8.2.37 | | |
| | time_metadata | 52 | nfstime4 | R | Section 5.8.2.38 | | | | time_metadata | 52 | nfstime4 | R | Section 5.8.2.38 | | |
| | time_modify | 53 | nfstime4 | R | Section 5.8.2.39 | | | | time_modify | 53 | nfstime4 | R | Section 5.8.2.39 | | |
| | time_modify_set | 54 | settime4 | W | Section 5.8.2.40 | | | | time_modify_set | 54 | settime4 | W | Section 5.8.2.40 | | |
| +-------------------+----+-----------------+-----+------------------+ | | +-------------------+----+-----------------+-----+------------------+ | |
|
| Table 4 | | | |
| | | Table 4: RECOMMENDED Attributes | |
| | | | |
| 5.8. Attribute Definitions | | 5.8. Attribute Definitions | |
| | | | |
| 5.8.1. Definitions of REQUIRED Attributes | | 5.8.1. Definitions of REQUIRED Attributes | |
| | | | |
| 5.8.1.1. Attribute 0: supported_attrs | | 5.8.1.1. Attribute 0: supported_attrs | |
| | | | |
| The bit vector that would retrieve all REQUIRED and RECOMMENDED | | The bit vector that would retrieve all REQUIRED and RECOMMENDED | |
| attributes that are supported for this object. The scope of this | | attributes that are supported for this object. The scope of this | |
| attribute applies to all objects with a matching fsid. | | attribute applies to all objects with a matching fsid. | |
| | | | |
| skipping to change at page 42, line 10 | | skipping to change at page 43, line 45 | |
| attribute is NF4BLK, NF4CHR, NF4SOCK, or NF4FIFO. | | attribute is NF4BLK, NF4CHR, NF4SOCK, or NF4FIFO. | |
| | | | |
| o The phrase "is a regular file" means that the object's type | | o The phrase "is a regular file" means that the object's type | |
| attribute is NF4REG or NF4NAMEDATTR. | | attribute is NF4REG or NF4NAMEDATTR. | |
| | | | |
| o The phrase "is a symbolic link" means that the object's type | | o The phrase "is a symbolic link" means that the object's type | |
| attribute is NF4LNK. | | attribute is NF4LNK. | |
| | | | |
| 5.8.1.3. Attribute 2: fh_expire_type | | 5.8.1.3. Attribute 2: fh_expire_type | |
| | | | |
|
| Server uses this to specify filehandle expiration behavior to the | | The server uses this to specify filehandle expiration behavior to the | |
| client. See Section 4 for additional description. | | client. See Section 4 for additional description. | |
| | | | |
| 5.8.1.4. Attribute 3: change | | 5.8.1.4. Attribute 3: change | |
| | | | |
| A value created by the server that the client can use to determine if | | A value created by the server that the client can use to determine if | |
| file data, directory contents, or attributes of the object have been | | file data, directory contents, or attributes of the object have been | |
| modified. The server MAY return the object's time_metadata attribute | | modified. The server MAY return the object's time_metadata attribute | |
| for this attribute's value but only if the file system object cannot | | for this attribute's value but only if the file system object cannot | |
| be updated more frequently than the resolution of time_metadata. | | be updated more frequently than the resolution of time_metadata. | |
| | | | |
| | | | |
| skipping to change at page 42, line 35 | | skipping to change at page 44, line 27 | |
| 5.8.1.6. Attribute 5: link_support | | 5.8.1.6. Attribute 5: link_support | |
| | | | |
| TRUE, if the object's file system supports hard links. | | TRUE, if the object's file system supports hard links. | |
| | | | |
| 5.8.1.7. Attribute 6: symlink_support | | 5.8.1.7. Attribute 6: symlink_support | |
| | | | |
| TRUE, if the object's file system supports symbolic links. | | TRUE, if the object's file system supports symbolic links. | |
| | | | |
| 5.8.1.8. Attribute 7: named_attr | | 5.8.1.8. Attribute 7: named_attr | |
| | | | |
|
| TRUE, if this object has named attributes. In other words, object | | TRUE, if this object has named attributes. In other words, this | |
| has a non-empty named attribute directory. | | object has a non-empty named attribute directory. | |
| | | | |
| 5.8.1.9. Attribute 8: fsid | | 5.8.1.9. Attribute 8: fsid | |
| | | | |
| Unique file system identifier for the file system holding this | | Unique file system identifier for the file system holding this | |
| object. The fsid attribute has major and minor components, each of | | object. The fsid attribute has major and minor components, each of | |
| which are of data type uint64_t. | | which are of data type uint64_t. | |
| | | | |
| 5.8.1.10. Attribute 9: unique_handles | | 5.8.1.10. Attribute 9: unique_handles | |
| | | | |
| TRUE, if two distinct filehandles are guaranteed to refer to two | | TRUE, if two distinct filehandles are guaranteed to refer to two | |
| different file system objects. | | different file system objects. | |
| | | | |
| 5.8.1.11. Attribute 10: lease_time | | 5.8.1.11. Attribute 10: lease_time | |
| | | | |
|
| Duration of the lease at server in seconds. | | Duration of the lease at the server in seconds. | |
| | | | |
| 5.8.1.12. Attribute 11: rdattr_error | | 5.8.1.12. Attribute 11: rdattr_error | |
| | | | |
| Error returned from an attempt to retrieve attributes during a | | Error returned from an attempt to retrieve attributes during a | |
| READDIR operation. | | READDIR operation. | |
| | | | |
| 5.8.1.13. Attribute 19: filehandle | | 5.8.1.13. Attribute 19: filehandle | |
| | | | |
| The filehandle of this object (primarily for READDIR requests). | | The filehandle of this object (primarily for READDIR requests). | |
| | | | |
| 5.8.2. Definitions of Uncategorized RECOMMENDED Attributes | | 5.8.2. Definitions of Uncategorized RECOMMENDED Attributes | |
| | | | |
| The definitions of most of the RECOMMENDED attributes follow. | | The definitions of most of the RECOMMENDED attributes follow. | |
| Collections that share a common category are defined in other | | Collections that share a common category are defined in other | |
| sections. | | sections. | |
| | | | |
| 5.8.2.1. Attribute 14: archive | | 5.8.2.1. Attribute 14: archive | |
| | | | |
|
| TRUE, if this file has been archived since the time of last | | TRUE, if this file has been archived since the time of the last | |
| modification (deprecated in favor of time_backup). | | modification (deprecated in favor of time_backup). | |
| | | | |
| 5.8.2.2. Attribute 15: cansettime | | 5.8.2.2. Attribute 15: cansettime | |
| | | | |
| TRUE, if the server is able to change the times for a file system | | TRUE, if the server is able to change the times for a file system | |
| object as specified in a SETATTR operation. | | object as specified in a SETATTR operation. | |
| | | | |
| 5.8.2.3. Attribute 16: case_insensitive | | 5.8.2.3. Attribute 16: case_insensitive | |
| | | | |
|
| TRUE, if file name comparisons on this file system are case | | TRUE, if filename comparisons on this file system are case | |
| insensitive. This refers only to comparisons, and not to the case in | | insensitive. This refers only to comparisons, and not to the case in | |
|
| which file names are stored. | | which filenames are stored. | |
| | | | |
| 5.8.2.4. Attribute 17: case_preserving | | 5.8.2.4. Attribute 17: case_preserving | |
| | | | |
|
| TRUE, if file name case on this file system is preserved. This | | TRUE, if the filename case on this file system is preserved. This | |
| refers only to how file names are stored, and not to how they are | | refers only to how filenames are stored, and not to how they are | |
| compared. File names stored in mixed case might be compared using | | compared. Filenames stored in mixed case might be compared using | |
| either case-insensitive or case-sensitive comparisons. | | either case-insensitive or case-sensitive comparisons. | |
| | | | |
| 5.8.2.5. Attribute 18: chown_restricted | | 5.8.2.5. Attribute 18: chown_restricted | |
| | | | |
| If TRUE, the server will reject any request to change either the | | If TRUE, the server will reject any request to change either the | |
| owner or the group associated with a file if the caller is not a | | owner or the group associated with a file if the caller is not a | |
| privileged user (for example, "root" in UNIX operating environments | | privileged user (for example, "root" in UNIX operating environments | |
|
| or in Windows 2000, the "Take Ownership" privilege). | | or the "Take Ownership" privilege in Windows 2000). | |
| | | | |
| 5.8.2.6. Attribute 20: fileid | | 5.8.2.6. Attribute 20: fileid | |
| | | | |
| A number uniquely identifying the file within the file system. | | A number uniquely identifying the file within the file system. | |
| | | | |
| 5.8.2.7. Attribute 21: files_avail | | 5.8.2.7. Attribute 21: files_avail | |
| | | | |
| File slots available to this user on the file system containing this | | File slots available to this user on the file system containing this | |
| object -- this should be the smallest relevant limit. | | object -- this should be the smallest relevant limit. | |
| | | | |
| 5.8.2.8. Attribute 22: files_free | | 5.8.2.8. Attribute 22: files_free | |
| | | | |
|
| Free file slots on the file system containing this object - this | | Free file slots on the file system containing this object -- this | |
| should be the smallest relevant limit. | | should be the smallest relevant limit. | |
| | | | |
| 5.8.2.9. Attribute 23: files_total | | 5.8.2.9. Attribute 23: files_total | |
| | | | |
| Total file slots on the file system containing this object. | | Total file slots on the file system containing this object. | |
| | | | |
| 5.8.2.10. Attribute 24: fs_locations | | 5.8.2.10. Attribute 24: fs_locations | |
| | | | |
| Locations where this file system may be found. If the server returns | | Locations where this file system may be found. If the server returns | |
| NFS4ERR_MOVED as an error, this attribute MUST be supported. | | NFS4ERR_MOVED as an error, this attribute MUST be supported. | |
| | | | |
|
| The server specifies the root path for a given server by returning a | | The server specifies the rootpath for a given server by returning a | |
| path consisting of zero path components. | | path consisting of zero path components. | |
| | | | |
| 5.8.2.11. Attribute 25: hidden | | 5.8.2.11. Attribute 25: hidden | |
| | | | |
|
| TRUE, if the file is considered hidden with respect to the Windows | | TRUE, if the file is considered hidden with respect to the | |
| API. | | Windows API. | |
| | | | |
| 5.8.2.12. Attribute 26: homogeneous | | 5.8.2.12. Attribute 26: homogeneous | |
| | | | |
| TRUE, if this object's file system is homogeneous, i.e., all objects | | TRUE, if this object's file system is homogeneous, i.e., all objects | |
| in the file system (all objects on the server with the same fsid) | | in the file system (all objects on the server with the same fsid) | |
|
| have common values for all per-file-system attributes. | | have common values for all per-file system attributes. | |
| | | | |
| 5.8.2.13. Attribute 27: maxfilesize | | 5.8.2.13. Attribute 27: maxfilesize | |
| | | | |
| Maximum supported file size for the file system of this object. | | Maximum supported file size for the file system of this object. | |
| | | | |
| 5.8.2.14. Attribute 28: maxlink | | 5.8.2.14. Attribute 28: maxlink | |
| | | | |
| Maximum number of hard links for this object. | | Maximum number of hard links for this object. | |
| | | | |
| 5.8.2.15. Attribute 29: maxname | | 5.8.2.15. Attribute 29: maxname | |
| | | | |
|
| Maximum file name size supported for this object. | | Maximum filename size supported for this object. | |
| | | | |
| 5.8.2.16. Attribute 30: maxread | | 5.8.2.16. Attribute 30: maxread | |
| | | | |
| Maximum amount of data the READ operation will return for this | | Maximum amount of data the READ operation will return for this | |
| object. | | object. | |
| | | | |
| 5.8.2.17. Attribute 31: maxwrite | | 5.8.2.17. Attribute 31: maxwrite | |
| | | | |
| Maximum amount of data the WRITE operation will accept for this | | Maximum amount of data the WRITE operation will accept for this | |
| object. This attribute SHOULD be supported if the file is writable. | | object. This attribute SHOULD be supported if the file is writable. | |
| | | | |
| skipping to change at page 45, line 35 | | skipping to change at page 47, line 26 | |
| 5.8.2.19. Attribute 55: mounted_on_fileid | | 5.8.2.19. Attribute 55: mounted_on_fileid | |
| | | | |
| Like fileid, but if the target filehandle is the root of a file | | Like fileid, but if the target filehandle is the root of a file | |
| system, this attribute represents the fileid of the underlying | | system, this attribute represents the fileid of the underlying | |
| directory. | | directory. | |
| | | | |
| UNIX-based operating environments connect a file system into the | | UNIX-based operating environments connect a file system into the | |
| namespace by connecting (mounting) the file system onto the existing | | namespace by connecting (mounting) the file system onto the existing | |
| file object (the mount point, usually a directory) of an existing | | file object (the mount point, usually a directory) of an existing | |
| file system. When the mount point's parent directory is read via an | | file system. When the mount point's parent directory is read via an | |
|
| API like readdir(), the return results are directory entries, each | | API such as readdir() [readdir_api], the return results are directory | |
| with a component name and a fileid. The fileid of the mount point's | | entries, each with a component name and a fileid. The fileid of the | |
| directory entry will be different from the fileid that the stat() | | mount point's directory entry will be different from the fileid that | |
| system call returns. The stat() system call is returning the fileid | | the stat() [stat] system call returns. The stat() system call is | |
| of the root of the mounted file system, whereas readdir() is | | returning the fileid of the root of the mounted file system, whereas | |
| returning the fileid that stat() would have returned before any file | | readdir() is returning the fileid that stat() would have returned | |
| systems were mounted on the mount point. | | before any file systems were mounted on the mount point. | |
| | | | |
| Unlike NFSv3, NFSv4.0 allows a client's LOOKUP request to cross other | | Unlike NFSv3, NFSv4.0 allows a client's LOOKUP request to cross other | |
| file systems. The client detects the file system crossing whenever | | file systems. The client detects the file system crossing whenever | |
| the filehandle argument of LOOKUP has an fsid attribute different | | the filehandle argument of LOOKUP has an fsid attribute different | |
| from that of the filehandle returned by LOOKUP. A UNIX-based client | | from that of the filehandle returned by LOOKUP. A UNIX-based client | |
| will consider this a "mount point crossing". UNIX has a legacy | | will consider this a "mount point crossing". UNIX has a legacy | |
| scheme for allowing a process to determine its current working | | scheme for allowing a process to determine its current working | |
| directory. This relies on readdir() of a mount point's parent and | | directory. This relies on readdir() of a mount point's parent and | |
| stat() of the mount point returning fileids as previously described. | | stat() of the mount point returning fileids as previously described. | |
| The mounted_on_fileid attribute corresponds to the fileid that | | The mounted_on_fileid attribute corresponds to the fileid that | |
|
| readdir() would have returned as described previously. | | readdir() would have returned, as described previously. | |
| | | | |
| While the NFSv4.0 client could simply fabricate a fileid | | While the NFSv4.0 client could simply fabricate a fileid | |
| corresponding to what mounted_on_fileid provides (and if the server | | corresponding to what mounted_on_fileid provides (and if the server | |
| does not support mounted_on_fileid, the client has no choice), there | | does not support mounted_on_fileid, the client has no choice), there | |
| is a risk that the client will generate a fileid that conflicts with | | is a risk that the client will generate a fileid that conflicts with | |
| one that is already assigned to another object in the file system. | | one that is already assigned to another object in the file system. | |
| Instead, if the server can provide the mounted_on_fileid, the | | Instead, if the server can provide the mounted_on_fileid, the | |
| potential for client operational problems in this area is eliminated. | | potential for client operational problems in this area is eliminated. | |
| | | | |
|
| If the server detects that there is no mounted point at the target | | If the server detects that there is nothing mounted on top of the | |
| file object, then the value for mounted_on_fileid that it returns is | | target file object, then the value for mounted_on_fileid that it | |
| the same as that of the fileid attribute. | | returns is the same as that of the fileid attribute. | |
| | | | |
| The mounted_on_fileid attribute is RECOMMENDED, so the server SHOULD | | The mounted_on_fileid attribute is RECOMMENDED, so the server SHOULD | |
| provide it if possible, and for a UNIX-based server, this is | | provide it if possible, and for a UNIX-based server, this is | |
| straightforward. Usually, mounted_on_fileid will be requested during | | straightforward. Usually, mounted_on_fileid will be requested during | |
|
| a READDIR operation, in which case it is trivial (at least for UNIX- | | a READDIR operation, in which case it is trivial (at least for | |
| based servers) to return mounted_on_fileid since it is equal to the | | UNIX-based servers) to return mounted_on_fileid since it is equal to | |
| fileid of a directory entry returned by readdir(). If | | the fileid of a directory entry returned by readdir(). If | |
| mounted_on_fileid is requested in a GETATTR operation, the server | | mounted_on_fileid is requested in a GETATTR operation, the server | |
| should obey an invariant that has it returning a value that is equal | | should obey an invariant that has it returning a value that is equal | |
| to the file object's entry in the object's parent directory, i.e., | | to the file object's entry in the object's parent directory, i.e., | |
| what readdir() would have returned. Some operating environments | | what readdir() would have returned. Some operating environments | |
| allow a series of two or more file systems to be mounted onto a | | allow a series of two or more file systems to be mounted onto a | |
| single mount point. In this case, for the server to obey the | | single mount point. In this case, for the server to obey the | |
| aforementioned invariant, it will need to find the base mount point, | | aforementioned invariant, it will need to find the base mount point, | |
| and not the intermediate mount points. | | and not the intermediate mount points. | |
| | | | |
| 5.8.2.20. Attribute 34: no_trunc | | 5.8.2.20. Attribute 34: no_trunc | |
| | | | |
|
| If this attribute is TRUE, then if the client uses a file name longer | | If this attribute is TRUE, then if the client uses a filename longer | |
| than name_max, an error will be returned instead of the name being | | than name_max, an error will be returned instead of the name being | |
| truncated. | | truncated. | |
| | | | |
| 5.8.2.21. Attribute 35: numlinks | | 5.8.2.21. Attribute 35: numlinks | |
| | | | |
| Number of hard links to this object. | | Number of hard links to this object. | |
| | | | |
| 5.8.2.22. Attribute 36: owner | | 5.8.2.22. Attribute 36: owner | |
| | | | |
| The string name of the owner of this object. | | The string name of the owner of this object. | |
| | | | |
| skipping to change at page 47, line 18 | | skipping to change at page 49, line 10 | |
| space beyond the current allocation that can be allocated to this | | space beyond the current allocation that can be allocated to this | |
| file or directory before further allocations will be refused. It is | | file or directory before further allocations will be refused. It is | |
| understood that this space may be consumed by allocations to other | | understood that this space may be consumed by allocations to other | |
| files or directories. | | files or directories. | |
| | | | |
| 5.8.2.25. Attribute 39: quota_avail_soft | | 5.8.2.25. Attribute 39: quota_avail_soft | |
| | | | |
| The value in bytes that represents the amount of additional disk | | The value in bytes that represents the amount of additional disk | |
| space that can be allocated to this file or directory before the user | | space that can be allocated to this file or directory before the user | |
| may reasonably be warned. It is understood that this space may be | | may reasonably be warned. It is understood that this space may be | |
|
| consumed by allocations to other files or directories though there | | consumed by allocations to other files or directories, though there | |
| may exist server side rules as to which other files or directories. | | may exist server-side rules as to which other files or directories. | |
| | | | |
| 5.8.2.26. Attribute 40: quota_used | | 5.8.2.26. Attribute 40: quota_used | |
| | | | |
| The value in bytes that represents the amount of disk space used by | | The value in bytes that represents the amount of disk space used by | |
| this file or directory and possibly a number of other similar files | | this file or directory and possibly a number of other similar files | |
| or directories, where the set of "similar" meets at least the | | or directories, where the set of "similar" meets at least the | |
| criterion that allocating space to any file or directory in the set | | criterion that allocating space to any file or directory in the set | |
| will reduce the "quota_avail_hard" of every other file or directory | | will reduce the "quota_avail_hard" of every other file or directory | |
| in the set. | | in the set. | |
| | | | |
| Note that there may be a number of distinct but overlapping sets of | | Note that there may be a number of distinct but overlapping sets of | |
| files or directories for which a quota_used value is maintained, | | files or directories for which a quota_used value is maintained, | |
| e.g., "all files with a given owner", "all files with a given group | | e.g., "all files with a given owner", "all files with a given group | |
| owner", etc. The server is at liberty to choose any of those sets | | owner", etc. The server is at liberty to choose any of those sets | |
|
| when providing the content of the quota_used attribute, but should do | | when providing the content of the quota_used attribute but should do | |
| so in a repeatable way. The rule may be configured per file system | | so in a repeatable way. The rule may be configured per file system | |
| or may be "choose the set with the smallest quota". | | or may be "choose the set with the smallest quota". | |
| | | | |
| 5.8.2.27. Attribute 41: rawdev | | 5.8.2.27. Attribute 41: rawdev | |
| | | | |
| Raw device number of file of type NF4BLK or NF4CHR. The device | | Raw device number of file of type NF4BLK or NF4CHR. The device | |
| number is split into major and minor numbers. If the file's type | | number is split into major and minor numbers. If the file's type | |
| attribute is not NF4BLK or NF4CHR, this attribute SHOULD NOT be | | attribute is not NF4BLK or NF4CHR, this attribute SHOULD NOT be | |
| returned, and any value returned SHOULD NOT be considered useful. | | returned, and any value returned SHOULD NOT be considered useful. | |
| | | | |
| | | | |
| skipping to change at page 48, line 20 | | skipping to change at page 50, line 11 | |
| 5.8.2.30. Attribute 44: space_total | | 5.8.2.30. Attribute 44: space_total | |
| | | | |
| Total disk space in bytes on the file system containing this object. | | Total disk space in bytes on the file system containing this object. | |
| | | | |
| 5.8.2.31. Attribute 45: space_used | | 5.8.2.31. Attribute 45: space_used | |
| | | | |
| Number of file system bytes allocated to this object. | | Number of file system bytes allocated to this object. | |
| | | | |
| 5.8.2.32. Attribute 46: system | | 5.8.2.32. Attribute 46: system | |
| | | | |
|
| This attribute is TRUE if this file is a "system" file with respect | | TRUE, if this file is a "system" file with respect to the Windows | |
| to the Windows operating environment. | | operating environment. | |
| | | | |
| 5.8.2.33. Attribute 47: time_access | | 5.8.2.33. Attribute 47: time_access | |
| | | | |
|
| The time_access attribute represents the time of last access to the | | Represents the time of last access to the object by a READ operation | |
| object by a READ operation sent to the server. The notion of what is | | sent to the server. The notion of what is an "access" depends on the | |
| an "access" depends on the server's operating environment and/or the | | server's operating environment and/or the server's file system | |
| server's file system semantics. For example, for servers obeying | | semantics. For example, for servers obeying Portable Operating | |
| Portable Operating System Interface (POSIX) semantics, time_access | | System Interface (POSIX) semantics, time_access would be updated only | |
| would be updated only by the READ and READDIR operations and not any | | by the READ and READDIR operations and not any of the operations that | |
| of the operations that modify the content of the object [16], [17], | | modify the content of the object [read_api], [readdir_api], | |
| [read_api], [readdir_api], [write_api]. Of course, setting the | | [write_api]. Of course, setting the corresponding time_access_set | |
| corresponding time_access_set attribute is another way to modify the | | attribute is another way to modify the time_access attribute. | |
| time_access attribute. | | | |
| | | | |
| Whenever the file object resides on a writable file system, the | | Whenever the file object resides on a writable file system, the | |
| server should make its best efforts to record time_access into stable | | server should make its best efforts to record time_access into stable | |
| storage. However, to mitigate the performance effects of doing so, | | storage. However, to mitigate the performance effects of doing so, | |
| and most especially whenever the server is satisfying the read of the | | and most especially whenever the server is satisfying the read of the | |
| object's content from its cache, the server MAY cache access time | | object's content from its cache, the server MAY cache access time | |
| updates and lazily write them to stable storage. It is also | | updates and lazily write them to stable storage. It is also | |
| acceptable to give administrators of the server the option to disable | | acceptable to give administrators of the server the option to disable | |
| time_access updates. | | time_access updates. | |
| | | | |
| 5.8.2.34. Attribute 48: time_access_set | | 5.8.2.34. Attribute 48: time_access_set | |
| | | | |
| Sets the time of last access to the object. SETATTR use only. | | Sets the time of last access to the object. SETATTR use only. | |
| | | | |
| 5.8.2.35. Attribute 49: time_backup | | 5.8.2.35. Attribute 49: time_backup | |
| | | | |
| The time of last backup of the object. | | The time of last backup of the object. | |
| | | | |
| 5.8.2.36. Attribute 50: time_create | | 5.8.2.36. Attribute 50: time_create | |
| | | | |
|
| The time of creation of the object. This attribute does not have any | | The time of creation of the object. This attribute does not have | |
| relation to the traditional UNIX file attribute "ctime" or "change | | any relation to the traditional UNIX file attribute "ctime" | |
| time". | | ("change time"). | |
| | | | |
| 5.8.2.37. Attribute 51: time_delta | | 5.8.2.37. Attribute 51: time_delta | |
| | | | |
| Smallest useful server time granularity. | | Smallest useful server time granularity. | |
| | | | |
| 5.8.2.38. Attribute 52: time_metadata | | 5.8.2.38. Attribute 52: time_metadata | |
| | | | |
| The time of last metadata modification of the object. | | The time of last metadata modification of the object. | |
| | | | |
| 5.8.2.39. Attribute 53: time_modify | | 5.8.2.39. Attribute 53: time_modify | |
| | | | |
| The time of last modification to the object. | | The time of last modification to the object. | |
| | | | |
| 5.8.2.40. Attribute 54: time_modify_set | | 5.8.2.40. Attribute 54: time_modify_set | |
| | | | |
| Sets the time of last modification to the object. SETATTR use only. | | Sets the time of last modification to the object. SETATTR use only. | |
| | | | |
| 5.9. Interpreting owner and owner_group | | 5.9. Interpreting owner and owner_group | |
| | | | |
| The RECOMMENDED attributes "owner" and "owner_group" (and also users | | The RECOMMENDED attributes "owner" and "owner_group" (and also users | |
|
| and groups used as values of the "who" field within nfs4ace | | and groups used as values of the who field within nfs4ace structures | |
| structures used in the acl attribute) are represented in the form of | | used in the acl attribute) are represented in the form of UTF-8 | |
| UTF-8 strings. This format avoids use of a representation that is | | strings. This format avoids the use of a representation that is tied | |
| tied to a particular underlying implementation at the client or | | to a particular underlying implementation at the client or server. | |
| server. Note that section 6.1 of [RFC2624] provides additional | | Note that Section 6.1 of [RFC2624] provides additional rationale. It | |
| rationale. It is expected that the client and server will have their | | is expected that the client and server will have their own local | |
| own local representation of owners and groups that is used for local | | representation of owners and groups that is used for local storage or | |
| storage or presentation to the application via API's that expect such | | presentation to the application via APIs that expect such a | |
| a representation. Therefore, the protocol requires that when these | | representation. Therefore, the protocol requires that when these | |
| attributes are transferred between the client and server, the local | | attributes are transferred between the client and server, the local | |
| representation is translated to a string of the form | | representation is translated to a string of the form | |
| "identifier@dns_domain". This allows clients and servers that do not | | "identifier@dns_domain". This allows clients and servers that do not | |
| use the same local representation to effectively interoperate since | | use the same local representation to effectively interoperate since | |
| they both use a common syntax that can be interpreted by both. | | they both use a common syntax that can be interpreted by both. | |
| | | | |
| Similarly, security principals may be represented in different ways | | Similarly, security principals may be represented in different ways | |
| by different security mechanisms. Servers normally translate these | | by different security mechanisms. Servers normally translate these | |
| representations into a common format, generally that used by local | | representations into a common format, generally that used by local | |
| storage, to serve as a means of identifying the users corresponding | | storage, to serve as a means of identifying the users corresponding | |
| | | | |
| skipping to change at page 50, line 17 | | skipping to change at page 51, line 52 | |
| users associated with each corresponding set of security principals. | | users associated with each corresponding set of security principals. | |
| | | | |
| The translation used to interpret owner and group strings is not | | The translation used to interpret owner and group strings is not | |
| specified as part of the protocol. This allows various solutions to | | specified as part of the protocol. This allows various solutions to | |
| be employed. For example, a local translation table may be consulted | | be employed. For example, a local translation table may be consulted | |
| that maps a numeric identifier to the user@dns_domain syntax. A name | | that maps a numeric identifier to the user@dns_domain syntax. A name | |
| service may also be used to accomplish the translation. A server may | | service may also be used to accomplish the translation. A server may | |
| provide a more general service, not limited by any particular | | provide a more general service, not limited by any particular | |
| translation (which would only translate a limited set of possible | | translation (which would only translate a limited set of possible | |
| strings) by storing the owner and owner_group attributes in local | | strings) by storing the owner and owner_group attributes in local | |
|
| storage without any translation or it may augment a translation | | storage without any translation, or it may augment a translation | |
| method by storing the entire string for attributes for which no | | method by storing the entire string for attributes for which no | |
| translation is available while using the local representation for | | translation is available while using the local representation for | |
| those cases in which a translation is available. | | those cases in which a translation is available. | |
| | | | |
| Servers that do not provide support for all possible values of user | | Servers that do not provide support for all possible values of user | |
| and group strings SHOULD return an error (NFS4ERR_BADOWNER) when a | | and group strings SHOULD return an error (NFS4ERR_BADOWNER) when a | |
| string is presented that has no translation, as the value to be set | | string is presented that has no translation, as the value to be set | |
| for a SETATTR of the owner or owner_group attributes or as part of | | for a SETATTR of the owner or owner_group attributes or as part of | |
|
| the value of the acl attribute When a server does accept a user or | | the value of the acl attribute. When a server does accept a user or | |
| group string as valid on a SETATTR, it is promising to return that | | group string as valid on a SETATTR, it is promising to return that | |
|
| same string (for which see below) when a corresponding GETATTR is | | same string (see below) when a corresponding GETATTR is done, as long | |
| done, as long as there has been no further change in the | | as there has been no further change in the corresponding attribute | |
| corresponding attribute before the GETATTR. For some | | before the GETATTR. For some internationalization-related exceptions | |
| internationalization-related exceptions where this is not possible, | | where this is not possible, see below. Configuration changes | |
| see below. Configuration changes (including changes from the mapping | | (including changes from the mapping of the string to the local | |
| of the string to the local representation) and ill-constructed name | | representation) and ill-constructed name translations (those that | |
| translations (those that contain aliasing) may make that promise | | contain aliasing) may make that promise impossible to honor. Servers | |
| impossible to honor. Servers should make appropriate efforts to | | should make appropriate efforts to avoid a situation in which these | |
| avoid a situation in which these attributes have their values changed | | attributes have their values changed when no real change to either | |
| when no real change to either ownership or acls has occurred. | | ownership or acls has occurred. | |
| | | | |
| The "dns_domain" portion of the owner string is meant to be a DNS | | The "dns_domain" portion of the owner string is meant to be a DNS | |
|
| domain name. For example, "user@example.org". Servers should accept | | domain name -- for example, "user@example.org". Servers should | |
| as valid a set of users for at least one domain. A server may treat | | accept as valid a set of users for at least one domain. A server may | |
| other domains as having no valid translations. A more general | | treat other domains as having no valid translations. A more general | |
| service is provided when a server is capable of accepting users for | | service is provided when a server is capable of accepting users for | |
| multiple domains, or for all domains, subject to security | | multiple domains, or for all domains, subject to security | |
| constraints. | | constraints. | |
| | | | |
| As an implementation guide, both clients and servers may provide a | | As an implementation guide, both clients and servers may provide a | |
| means to configure the "dns_domain" portion of the owner string. For | | means to configure the "dns_domain" portion of the owner string. For | |
| example, the DNS domain name of the host running the NFS server might | | example, the DNS domain name of the host running the NFS server might | |
| be "lab.example.org", but the user names are defined in | | be "lab.example.org", but the user names are defined in | |
| "example.org". In the absence of such a configuration, or as a | | "example.org". In the absence of such a configuration, or as a | |
| default, the current DNS domain name of the server should be the | | default, the current DNS domain name of the server should be the | |
| value used for the "dns_domain". | | value used for the "dns_domain". | |
| | | | |
|
| As mentioned above, it is desirable that a server when accepting a | | As mentioned above, it is desirable that a server, when accepting a | |
| string of the form "user@domain" or "group@domain" in an attribute, | | string of the form "user@domain" or "group@domain" in an attribute, | |
| return this same string when that corresponding attribute is fetched. | | return this same string when that corresponding attribute is fetched. | |
| Internationalization issues make this impossible under certain | | Internationalization issues make this impossible under certain | |
|
| circumstances and the client needs to take note of these. See | | circumstances, and the client needs to take note of these. See | |
| Section 12 for a detailed discussion of these issues. | | Section 12 for a detailed discussion of these issues. | |
| | | | |
| In the case where there is no translation available to the client or | | In the case where there is no translation available to the client or | |
| server, the attribute value will be constructed without the "@". | | server, the attribute value will be constructed without the "@". | |
| Therefore, the absence of the "@" from the owner or owner_group | | Therefore, the absence of the "@" from the owner or owner_group | |
| attribute signifies that no translation was available at the sender | | attribute signifies that no translation was available at the sender | |
| and that the receiver of the attribute should not use that string as | | and that the receiver of the attribute should not use that string as | |
| a basis for translation into its own internal format. Even though | | a basis for translation into its own internal format. Even though | |
| the attribute value cannot be translated, it may still be useful. In | | the attribute value cannot be translated, it may still be useful. In | |
| the case of a client, the attribute string may be used for local | | the case of a client, the attribute string may be used for local | |
| | | | |
| skipping to change at page 51, line 34 | | skipping to change at page 53, line 20 | |
| To provide a greater degree of compatibility with NFSv3, which | | To provide a greater degree of compatibility with NFSv3, which | |
| identified users and groups by 32-bit unsigned user identifiers and | | identified users and groups by 32-bit unsigned user identifiers and | |
| group identifiers, owner and group strings that consist of ASCII- | | group identifiers, owner and group strings that consist of ASCII- | |
| encoded decimal numeric values with no leading zeros can be given a | | encoded decimal numeric values with no leading zeros can be given a | |
| special interpretation by clients and servers that choose to provide | | special interpretation by clients and servers that choose to provide | |
| such support. The receiver may treat such a user or group string as | | such support. The receiver may treat such a user or group string as | |
| representing the same user as would be represented by an NFSv3 uid or | | representing the same user as would be represented by an NFSv3 uid or | |
| gid having the corresponding numeric value. | | gid having the corresponding numeric value. | |
| | | | |
| A server SHOULD reject such a numeric value if the security mechanism | | A server SHOULD reject such a numeric value if the security mechanism | |
|
| is using Kerberos. I.e., in such a scenario, the client will already | | is using Kerberos. That is, in such a scenario, the client will | |
| need to form "user@domain" strings. For any other security | | already need to form "user@domain" strings. For any other security | |
| mechanism, the server SHOULD accept such numeric values. As an | | mechanism, the server SHOULD accept such numeric values. As an | |
| implementation note, the server could make such an acceptance be | | implementation note, the server could make such an acceptance be | |
| configurable. If the server does not support numeric values or if it | | configurable. If the server does not support numeric values or if it | |
| is configured off, then it MUST return an NFS4ERR_BADOWNER error. If | | is configured off, then it MUST return an NFS4ERR_BADOWNER error. If | |
| the security mechanism is using Kerberos and the client attempts to | | the security mechanism is using Kerberos and the client attempts to | |
| use the special form, then the server SHOULD return an | | use the special form, then the server SHOULD return an | |
| NFS4ERR_BADOWNER error when there is a valid translation for the user | | NFS4ERR_BADOWNER error when there is a valid translation for the user | |
| or owner designated in this way. In that case, the client must use | | or owner designated in this way. In that case, the client must use | |
| the appropriate user@domain string and not the special form for | | the appropriate user@domain string and not the special form for | |
| compatibility. | | compatibility. | |
| | | | |
| The client MUST always accept numeric values if the security | | The client MUST always accept numeric values if the security | |
| mechanism is not RPCSEC_GSS. A client can determine if a server | | mechanism is not RPCSEC_GSS. A client can determine if a server | |
| supports numeric identifiers by first attempting to provide a numeric | | supports numeric identifiers by first attempting to provide a numeric | |
|
| identifier. If this attempt rejected with an NFS4ERR_BADOWNER error, | | identifier. If this attempt is rejected with an NFS4ERR_BADOWNER | |
| then the client should only use named identifiers of the form | | error, then the client should only use named identifiers of the form | |
| "user@dns_domain". | | "user@dns_domain". | |
| | | | |
| The owner string "nobody" may be used to designate an anonymous user, | | The owner string "nobody" may be used to designate an anonymous user, | |
| which will be associated with a file created by a security principal | | which will be associated with a file created by a security principal | |
| that cannot be mapped through normal means to the owner attribute. | | that cannot be mapped through normal means to the owner attribute. | |
| | | | |
| 5.10. Character Case Attributes | | 5.10. Character Case Attributes | |
| | | | |
| With respect to the case_insensitive and case_preserving attributes, | | With respect to the case_insensitive and case_preserving attributes, | |
|
| case insensitive comparisons of Unicode characters SHOULD use Unicode | | case-insensitive comparisons of Unicode characters SHOULD use Unicode | |
| Default Case Folding as defined in Chapter 3 of the Unicode Standard | | Default Case Folding as defined in Chapter 3 of the Unicode Standard | |
|
| [UNICODE], and MAY override that behavior for specific selected | | [UNICODE] and MAY override that behavior for specific selected | |
| characters with the case folding defined in the SpecialCasing.txt | | characters with the case folding defined in the SpecialCasing.txt | |
|
| [SPECIALCASING] file in section 3.13 of the Unicode Standard. | | [SPECIALCASING] file; see Section 3.13 of the Unicode Standard. | |
| | | | |
| The SpecialCasing.txt file replaces the Default Case Folding with | | The SpecialCasing.txt file replaces the Default Case Folding with | |
|
| locale and context-dependent case folding for specific situations. | | locale- and context-dependent case folding for specific situations. | |
| An example of locale and context-dependent case folding is that LATIN | | An example of locale- and context-dependent case folding is that | |
| CAPITAL LETTER I ("I", U+0049) is default case folded to LATIN SMALL | | LATIN CAPITAL LETTER I ("I", U+0049) is default case folded to LATIN | |
| LETTER I ("i", U+0069); however, several languages (e.g. Turkish) | | SMALL LETTER I ("i", U+0069). However, several languages (e.g., | |
| treat an "I" character with a dot as a different letter than an "I" | | Turkish) treat an "I" character with a dot as a different letter than | |
| character without a dot, therefore in such languages, unless an I is | | an "I" character without a dot; therefore, in such languages, unless | |
| before a dot_above, the "I" (U+0049) character should be case folded | | an I is before a dot_above, the "I" (U+0049) character should be case | |
| to a different character, LATIN SMALL LETTER DOTLESS I (U+0131). | | folded to a different character, LATIN SMALL LETTER DOTLESS I | |
| | | (U+0131). | |
| | | | |
| The [UNICODE] and [SPECIALCASING] references in this RFC are for | | The [UNICODE] and [SPECIALCASING] references in this RFC are for | |
|
| version 6.3.0 of the Unicode standard, as that was the latest version | | version 7.0.0 of the Unicode standard, as that was the latest version | |
| of Unicode when this RFC was published. Implementations SHOULD | | of Unicode when this RFC was published. Implementations SHOULD | |
|
| always use the latest version of Unicode (http://www.unicode.org/ | | always use the latest version of Unicode | |
| versions/latest/). | | (<http://www.unicode.org/versions/latest/>). | |
| | | | |
| [RFC Editor: please check that 6.3.0 is the latest version before | | | |
| publication of this document as an RFC.] | | | |
| | | | |
| 6. Access Control Attributes | | 6. Access Control Attributes | |
| | | | |
|
| Access Control Lists (ACLs) are file attributes that specify fine | | Access Control Lists (ACLs) are file attributes that specify fine- | |
| grained access control. This chapter covers the "acl", "aclsupport", | | grained access control. This section covers the "acl", "aclsupport", | |
| "mode", file attributes, and their interactions. Note that file | | and "mode" file attributes, and their interactions. Note that file | |
| attributes may apply to any file system object. | | attributes may apply to any file system object. | |
| | | | |
| 6.1. Goals | | 6.1. Goals | |
| | | | |
|
| ACLs and modes represent two well established models for specifying | | ACLs and modes represent two well-established models for specifying | |
| permissions. This chapter specifies requirements that attempt to | | permissions. This section specifies requirements that attempt to | |
| meet the following goals: | | meet the following goals: | |
| | | | |
| o If a server supports the mode attribute, it should provide | | o If a server supports the mode attribute, it should provide | |
| reasonable semantics to clients that only set and retrieve the | | reasonable semantics to clients that only set and retrieve the | |
| mode attribute. | | mode attribute. | |
| | | | |
| o If a server supports ACL attributes, it should provide reasonable | | o If a server supports ACL attributes, it should provide reasonable | |
| semantics to clients that only set and retrieve those attributes. | | semantics to clients that only set and retrieve those attributes. | |
| | | | |
| o On servers that support the mode attribute, if ACL attributes have | | o On servers that support the mode attribute, if ACL attributes have | |
| | | | |
| skipping to change at page 53, line 33 | | skipping to change at page 55, line 14 | |
| | | | |
| * Setting only the mode attribute should provide reasonable | | * Setting only the mode attribute should provide reasonable | |
| security. For example, setting a mode of 000 should be enough | | security. For example, setting a mode of 000 should be enough | |
| to ensure that future opens for read or write by any principal | | to ensure that future opens for read or write by any principal | |
| fail, regardless of a previously existing or inherited ACL. | | fail, regardless of a previously existing or inherited ACL. | |
| | | | |
| o When a mode attribute is set on an object, the ACL attributes may | | o When a mode attribute is set on an object, the ACL attributes may | |
| need to be modified so as to not conflict with the new mode. In | | need to be modified so as to not conflict with the new mode. In | |
| such cases, it is desirable that the ACL keep as much information | | such cases, it is desirable that the ACL keep as much information | |
| as possible. This includes information about inheritance, AUDIT | | as possible. This includes information about inheritance, AUDIT | |
|
| and ALARM ACEs, and permissions granted and denied that do not | | and ALARM access control entries (ACEs), and permissions granted | |
| conflict with the new mode. | | and denied that do not conflict with the new mode. | |
| | | | |
| 6.2. File Attributes Discussion | | 6.2. File Attributes Discussion | |
| | | | |
| Support for each of the ACL attributes is RECOMMENDED and not | | Support for each of the ACL attributes is RECOMMENDED and not | |
|
| required, since file systems accessed using NFSV4 might not support | | required, since file systems accessed using NFSv4 might not | |
| ACL's. | | support ACLs. | |
| | | | |
| 6.2.1. Attribute 12: acl | | 6.2.1. Attribute 12: acl | |
| | | | |
|
| The NFSv4.0 ACL attribute contains an array of access control entries | | The NFSv4.0 ACL attribute contains an array of ACEs that are | |
| (ACEs) that are associated with the file system object. Although the | | associated with the file system object. Although the client can read | |
| client can read and write the acl attribute, the server is | | and write the acl attribute, the server is responsible for using the | |
| responsible for using the ACL to perform access control. The client | | ACL to perform access control. The client can use the OPEN or ACCESS | |
| can use the OPEN or ACCESS operations to check access without | | operations to check access without modifying or reading data or | |
| modifying or reading data or metadata. | | metadata. | |
| | | | |
| The NFS ACE structure is defined as follows: | | The NFS ACE structure is defined as follows: | |
| | | | |
| typedef uint32_t acetype4; | | typedef uint32_t acetype4; | |
| | | | |
| typedef uint32_t aceflag4; | | typedef uint32_t aceflag4; | |
| | | | |
| typedef uint32_t acemask4; | | typedef uint32_t acemask4; | |
| | | | |
| struct nfsace4 { | | struct nfsace4 { | |
| acetype4 type; | | acetype4 type; | |
| aceflag4 flag; | | aceflag4 flag; | |
| acemask4 access_mask; | | acemask4 access_mask; | |
| utf8str_mixed who; | | utf8str_mixed who; | |
| }; | | }; | |
| | | | |
| To determine if a request succeeds, the server processes each nfsace4 | | To determine if a request succeeds, the server processes each nfsace4 | |
|
| entry in order. Only ACEs which have a "who" that matches the | | entry in order. Only ACEs that have a "who" that matches the | |
| requester are considered. Each ACE is processed until all of the | | requester are considered. Each ACE is processed until all of the | |
| bits of the requester's access have been ALLOWED. Once a bit (see | | bits of the requester's access have been ALLOWED. Once a bit (see | |
| below) has been ALLOWED by an ACCESS_ALLOWED_ACE, it is no longer | | below) has been ALLOWED by an ACCESS_ALLOWED_ACE, it is no longer | |
| considered in the processing of later ACEs. If an ACCESS_DENIED_ACE | | considered in the processing of later ACEs. If an ACCESS_DENIED_ACE | |
| is encountered where the requester's access still has unALLOWED bits | | is encountered where the requester's access still has unALLOWED bits | |
| in common with the "access_mask" of the ACE, the request is denied. | | in common with the "access_mask" of the ACE, the request is denied. | |
| When the ACL is fully processed, if there are bits in the requester's | | When the ACL is fully processed, if there are bits in the requester's | |
| mask that have not been ALLOWED or DENIED, access is denied. | | mask that have not been ALLOWED or DENIED, access is denied. | |
| | | | |
| Unlike the ALLOW and DENY ACE types, the ALARM and AUDIT ACE types do | | Unlike the ALLOW and DENY ACE types, the ALARM and AUDIT ACE types do | |
|
| not affect a requester's access, and instead are for triggering | | not affect a requester's access and instead are for triggering events | |
| events as a result of a requester's access attempt. Therefore, AUDIT | | as a result of a requester's access attempt. Therefore, AUDIT and | |
| and ALARM ACEs are processed only after processing ALLOW and DENY | | ALARM ACEs are processed only after processing ALLOW and DENY ACEs. | |
| ACEs. | | | |
| | | | |
| The NFSv4.0 ACL model is quite rich. Some server platforms may | | The NFSv4.0 ACL model is quite rich. Some server platforms may | |
| provide access control functionality that goes beyond the UNIX-style | | provide access control functionality that goes beyond the UNIX-style | |
|
| mode attribute, but which is not as rich as the NFS ACL model. So | | mode attribute but that is not as rich as the NFS ACL model. So that | |
| that users can take advantage of this more limited functionality, the | | users can take advantage of this more limited functionality, the | |
| server may support the acl attributes by mapping between its ACL | | server may support the acl attributes by mapping between its ACL | |
| model and the NFSv4.0 ACL model. Servers must ensure that the ACL | | model and the NFSv4.0 ACL model. Servers must ensure that the ACL | |
| they actually store or enforce is at least as strict as the NFSv4 ACL | | they actually store or enforce is at least as strict as the NFSv4 ACL | |
| that was set. It is tempting to accomplish this by rejecting any ACL | | that was set. It is tempting to accomplish this by rejecting any ACL | |
| that falls outside the small set that can be represented accurately. | | that falls outside the small set that can be represented accurately. | |
| However, such an approach can render ACLs unusable without special | | However, such an approach can render ACLs unusable without special | |
| client-side knowledge of the server's mapping, which defeats the | | client-side knowledge of the server's mapping, which defeats the | |
|
| purpose of having a common NFSv4 ACL protocol. Therefore servers | | purpose of having a common NFSv4 ACL protocol. Therefore, servers | |
| should accept every ACL that they can without compromising security. | | should accept every ACL that they can without compromising security. | |
| To help accomplish this, servers may make a special exception, in the | | To help accomplish this, servers may make a special exception, in the | |
| case of unsupported permission bits, to the rule that bits not | | case of unsupported permission bits, to the rule that bits not | |
| ALLOWED or DENIED by an ACL must be denied. For example, a UNIX- | | ALLOWED or DENIED by an ACL must be denied. For example, a UNIX- | |
| style server might choose to silently allow read attribute | | style server might choose to silently allow read attribute | |
| permissions even though an ACL does not explicitly allow those | | permissions even though an ACL does not explicitly allow those | |
| permissions. (An ACL that explicitly denies permission to read | | permissions. (An ACL that explicitly denies permission to read | |
| attributes should still result in a denial.) | | attributes should still result in a denial.) | |
| | | | |
| The situation is complicated by the fact that a server may have | | The situation is complicated by the fact that a server may have | |
| | | | |
| skipping to change at page 56, line 12 | | skipping to change at page 57, line 23 | |
| | | | |
| All four bit types are permitted in the acl attribute. | | All four bit types are permitted in the acl attribute. | |
| | | | |
| +------------------------------+--------------+---------------------+ | | +------------------------------+--------------+---------------------+ | |
| | Value | Abbreviation | Description | | | | Value | Abbreviation | Description | | |
| +------------------------------+--------------+---------------------+ | | +------------------------------+--------------+---------------------+ | |
| | ACE4_ACCESS_ALLOWED_ACE_TYPE | ALLOW | Explicitly grants | | | | ACE4_ACCESS_ALLOWED_ACE_TYPE | ALLOW | Explicitly grants | | |
| | | | the access defined | | | | | | the access defined | | |
| | | | in acemask4 to the | | | | | | in acemask4 to the | | |
| | | | file or directory. | | | | | | file or directory. | | |
|
| | | | | | | | |
| | ACE4_ACCESS_DENIED_ACE_TYPE | DENY | Explicitly denies | | | | ACE4_ACCESS_DENIED_ACE_TYPE | DENY | Explicitly denies | | |
| | | | the access defined | | | | | | the access defined | | |
| | | | in acemask4 to the | | | | | | in acemask4 to the | | |
| | | | file or directory. | | | | | | file or directory. | | |
|
| | ACE4_SYSTEM_AUDIT_ACE_TYPE | AUDIT | LOG (in a system | | | | | | | | |
| | | | ACE4_SYSTEM_AUDIT_ACE_TYPE | AUDIT | LOG (in a system- | | |
| | | | dependent way) any | | | | | | dependent way) any | | |
| | | | access attempt to a | | | | | | access attempt to a | | |
| | | | file or directory | | | | | | file or directory | | |
|
| | | | which uses any of | | | | | | that uses any of | | |
| | | | the access methods | | | | | | the access methods | | |
| | | | specified in | | | | | | specified in | | |
| | | | acemask4. | | | | | | acemask4. | | |
|
| | | | | | | | |
| | ACE4_SYSTEM_ALARM_ACE_TYPE | ALARM | Generate a system | | | | ACE4_SYSTEM_ALARM_ACE_TYPE | ALARM | Generate a system | | |
| | | | ALARM (system | | | | | | ALARM (system | | |
| | | | dependent) when any | | | | | | dependent) when any | | |
| | | | access attempt is | | | | | | access attempt is | | |
| | | | made to a file or | | | | | | made to a file or | | |
| | | | directory for the | | | | | | directory for the | | |
| | | | access methods | | | | | | access methods | | |
| | | | specified in | | | | | | specified in | | |
| | | | acemask4. | | | | | | acemask4. | | |
| +------------------------------+--------------+---------------------+ | | +------------------------------+--------------+---------------------+ | |
| | | | |
| The "Abbreviation" column denotes how the types will be referred to | | The "Abbreviation" column denotes how the types will be referred to | |
|
| throughout the rest of this chapter. | | throughout the rest of this section. | |
| | | | |
| 6.2.1.2. Attribute 13: aclsupport | | 6.2.1.2. Attribute 13: aclsupport | |
| | | | |
| A server need not support all of the above ACE types. This attribute | | A server need not support all of the above ACE types. This attribute | |
| indicates which ACE types are supported for the current file system. | | indicates which ACE types are supported for the current file system. | |
| The bitmask constants used to represent the above definitions within | | The bitmask constants used to represent the above definitions within | |
| the aclsupport attribute are as follows: | | the aclsupport attribute are as follows: | |
| | | | |
| const ACL4_SUPPORT_ALLOW_ACL = 0x00000001; | | const ACL4_SUPPORT_ALLOW_ACL = 0x00000001; | |
| const ACL4_SUPPORT_DENY_ACL = 0x00000002; | | const ACL4_SUPPORT_DENY_ACL = 0x00000002; | |
| const ACL4_SUPPORT_AUDIT_ACL = 0x00000004; | | const ACL4_SUPPORT_AUDIT_ACL = 0x00000004; | |
| const ACL4_SUPPORT_ALARM_ACL = 0x00000008; | | const ACL4_SUPPORT_ALARM_ACL = 0x00000008; | |
| | | | |
|
| Servers which support either the ALLOW or DENY ACE type SHOULD | | Servers that support either the ALLOW or DENY ACE type SHOULD support | |
| support both ALLOW and DENY ACE types. | | both ALLOW and DENY ACE types. | |
| | | | |
| Clients should not attempt to set an ACE unless the server claims | | Clients should not attempt to set an ACE unless the server claims | |
| support for that ACE type. If the server receives a request to set | | support for that ACE type. If the server receives a request to set | |
| an ACE that it cannot store, it MUST reject the request with | | an ACE that it cannot store, it MUST reject the request with | |
| NFS4ERR_ATTRNOTSUPP. If the server receives a request to set an ACE | | NFS4ERR_ATTRNOTSUPP. If the server receives a request to set an ACE | |
| that it can store but cannot enforce, the server SHOULD reject the | | that it can store but cannot enforce, the server SHOULD reject the | |
| request with NFS4ERR_ATTRNOTSUPP. | | request with NFS4ERR_ATTRNOTSUPP. | |
| | | | |
| 6.2.1.3. ACE Access Mask | | 6.2.1.3. ACE Access Mask | |
| | | | |
| | | | |
| skipping to change at page 57, line 34 | | skipping to change at page 59, line 4 | |
| const ACE4_EXECUTE = 0x00000020; | | const ACE4_EXECUTE = 0x00000020; | |
| const ACE4_DELETE_CHILD = 0x00000040; | | const ACE4_DELETE_CHILD = 0x00000040; | |
| const ACE4_READ_ATTRIBUTES = 0x00000080; | | const ACE4_READ_ATTRIBUTES = 0x00000080; | |
| const ACE4_WRITE_ATTRIBUTES = 0x00000100; | | const ACE4_WRITE_ATTRIBUTES = 0x00000100; | |
| | | | |
| const ACE4_DELETE = 0x00010000; | | const ACE4_DELETE = 0x00010000; | |
| const ACE4_READ_ACL = 0x00020000; | | const ACE4_READ_ACL = 0x00020000; | |
| const ACE4_WRITE_ACL = 0x00040000; | | const ACE4_WRITE_ACL = 0x00040000; | |
| const ACE4_WRITE_OWNER = 0x00080000; | | const ACE4_WRITE_OWNER = 0x00080000; | |
| const ACE4_SYNCHRONIZE = 0x00100000; | | const ACE4_SYNCHRONIZE = 0x00100000; | |
|
| | | Note that some masks have coincident values -- for example, | |
| Note that some masks have coincident values, for example, | | | |
| ACE4_READ_DATA and ACE4_LIST_DIRECTORY. The mask entries | | ACE4_READ_DATA and ACE4_LIST_DIRECTORY. The mask entries | |
| ACE4_LIST_DIRECTORY, ACE4_ADD_FILE, and ACE4_ADD_SUBDIRECTORY are | | ACE4_LIST_DIRECTORY, ACE4_ADD_FILE, and ACE4_ADD_SUBDIRECTORY are | |
| intended to be used with directory objects, while ACE4_READ_DATA, | | intended to be used with directory objects, while ACE4_READ_DATA, | |
| ACE4_WRITE_DATA, and ACE4_APPEND_DATA are intended to be used with | | ACE4_WRITE_DATA, and ACE4_APPEND_DATA are intended to be used with | |
| non-directory objects. | | non-directory objects. | |
| | | | |
| 6.2.1.3.1. Discussion of Mask Attributes | | 6.2.1.3.1. Discussion of Mask Attributes | |
| | | | |
| ACE4_READ_DATA | | ACE4_READ_DATA | |
| | | | |
| | | | |
| skipping to change at page 59, line 48 | | skipping to change at page 61, line 27 | |
| operation is always affected. | | operation is always affected. | |
| | | | |
| ACE4_READ_NAMED_ATTRS | | ACE4_READ_NAMED_ATTRS | |
| | | | |
| Operation(s) affected: | | Operation(s) affected: | |
| | | | |
| OPENATTR | | OPENATTR | |
| | | | |
| Discussion: | | Discussion: | |
| | | | |
|
| Permission to read the named attributes of a file or to lookup | | Permission to read the named attributes of a file or to look up | |
| the named attributes directory. OPENATTR is affected when it | | the named attributes directory. OPENATTR is affected when it | |
| is not used to create a named attribute directory. This is | | is not used to create a named attribute directory. This is | |
|
| when 1.) createdir is TRUE, but a named attribute directory | | when 1) createdir is TRUE but a named attribute directory | |
| already exists, or 2.) createdir is FALSE. | | already exists or 2) createdir is FALSE. | |
| | | | |
| ACE4_WRITE_NAMED_ATTRS | | ACE4_WRITE_NAMED_ATTRS | |
| | | | |
| Operation(s) affected: | | Operation(s) affected: | |
| | | | |
| OPENATTR | | OPENATTR | |
| | | | |
| Discussion: | | Discussion: | |
| | | | |
| Permission to write the named attributes of a file or to create | | Permission to write the named attributes of a file or to create | |
| a named attribute directory. OPENATTR is affected when it is | | a named attribute directory. OPENATTR is affected when it is | |
| used to create a named attribute directory. This is when | | used to create a named attribute directory. This is when | |
| createdir is TRUE and no named attribute directory exists. The | | createdir is TRUE and no named attribute directory exists. The | |
| ability to check whether or not a named attribute directory | | ability to check whether or not a named attribute directory | |
|
| exists depends on the ability to look it up, therefore, users | | exists depends on the ability to look it up; therefore, users | |
| also need the ACE4_READ_NAMED_ATTRS permission in order to | | also need the ACE4_READ_NAMED_ATTRS permission in order to | |
| create a named attribute directory. | | create a named attribute directory. | |
| | | | |
| ACE4_EXECUTE | | ACE4_EXECUTE | |
| | | | |
| Operation(s) affected: | | Operation(s) affected: | |
| | | | |
| READ | | READ | |
| | | | |
| Discussion: | | Discussion: | |
| | | | |
| Permission to execute a file. | | Permission to execute a file. | |
| | | | |
| Servers SHOULD allow a user the ability to read the data of the | | Servers SHOULD allow a user the ability to read the data of the | |
| file when only the ACE4_EXECUTE access mask bit is set. This | | file when only the ACE4_EXECUTE access mask bit is set. This | |
| is because there is no way to execute a file without reading | | is because there is no way to execute a file without reading | |
| the contents. Though a server may treat ACE4_EXECUTE and | | the contents. Though a server may treat ACE4_EXECUTE and | |
| ACE4_READ_DATA bits identically when deciding to permit a READ | | ACE4_READ_DATA bits identically when deciding to permit a READ | |
| operation, it SHOULD still allow the two bits to be set | | operation, it SHOULD still allow the two bits to be set | |
|
| independently in ACLs, and MUST distinguish between them when | | independently in ACLs and MUST distinguish between them when | |
| replying to ACCESS operations. In particular, servers SHOULD | | replying to ACCESS operations. In particular, servers SHOULD | |
| NOT silently turn on one of the two bits when the other is set, | | NOT silently turn on one of the two bits when the other is set, | |
| as that would make it impossible for the client to correctly | | as that would make it impossible for the client to correctly | |
| enforce the distinction between read and execute permissions. | | enforce the distinction between read and execute permissions. | |
| | | | |
| As an example, following a SETATTR of the following ACL: | | As an example, following a SETATTR of the following ACL: | |
| | | | |
| nfsuser:ACE4_EXECUTE:ALLOW | | nfsuser:ACE4_EXECUTE:ALLOW | |
|
| | | | |
| A subsequent GETATTR of ACL for that file SHOULD return: | | A subsequent GETATTR of ACL for that file SHOULD return: | |
| | | | |
| nfsuser:ACE4_EXECUTE:ALLOW | | nfsuser:ACE4_EXECUTE:ALLOW | |
| | | | |
| Rather than: | | Rather than: | |
| | | | |
| nfsuser:ACE4_EXECUTE/ACE4_READ_DATA:ALLOW | | nfsuser:ACE4_EXECUTE/ACE4_READ_DATA:ALLOW | |
| | | | |
| ACE4_EXECUTE | | ACE4_EXECUTE | |
| | | | |
| | | | |
| skipping to change at page 62, line 4 | | skipping to change at page 64, line 10 | |
| | | | |
| Permission to delete a file or directory within a directory. | | Permission to delete a file or directory within a directory. | |
| See Section 6.2.1.3.2 for information on how ACE4_DELETE and | | See Section 6.2.1.3.2 for information on how ACE4_DELETE and | |
| ACE4_DELETE_CHILD interact. | | ACE4_DELETE_CHILD interact. | |
| | | | |
| ACE4_READ_ATTRIBUTES | | ACE4_READ_ATTRIBUTES | |
| | | | |
| Operation(s) affected: | | Operation(s) affected: | |
| | | | |
| GETATTR of file system object attributes | | GETATTR of file system object attributes | |
|
| | | | |
| VERIFY | | VERIFY | |
| | | | |
| NVERIFY | | NVERIFY | |
| | | | |
| READDIR | | READDIR | |
| | | | |
| Discussion: | | Discussion: | |
| | | | |
|
| The ability to read basic attributes (non-ACLs) of a file. On | | The ability to read basic attributes (non-ACLs) of a file. | |
| a UNIX system, basic attributes can be thought of as the stat | | On a UNIX system, basic attributes can be thought of as the | |
| level attributes. Allowing this access mask bit would mean the | | stat-level attributes. Allowing this access mask bit would | |
| entity can execute "ls -l" and stat. If a READDIR operation | | mean the entity can execute "ls -l" and stat. If a READDIR | |
| requests attributes, this mask must be allowed for the READDIR | | operation requests attributes, this mask must be allowed for | |
| to succeed. | | the READDIR to succeed. | |
| | | | |
| ACE4_WRITE_ATTRIBUTES | | ACE4_WRITE_ATTRIBUTES | |
| | | | |
| Operation(s) affected: | | Operation(s) affected: | |
| | | | |
|
| SETATTR of time_access_set, time_backup, | | SETATTR of time_access_set, time_backup, time_create, | |
| | | time_modify_set, mimetype, hidden, and system | |
| time_create, time_modify_set, mimetype, hidden, system | | | |
| | | | |
| Discussion: | | Discussion: | |
| | | | |
| Permission to change the times associated with a file or | | Permission to change the times associated with a file or | |
|
| directory to an arbitrary value. Also permission to change the | | directory to an arbitrary value. Also, permission to change | |
| mimetype, hidden and system attributes. A user having | | the mimetype, hidden and system attributes. A user having | |
| ACE4_WRITE_DATA or ACE4_WRITE_ATTRIBUTES will be allowed to set | | ACE4_WRITE_DATA or ACE4_WRITE_ATTRIBUTES will be allowed to set | |
| the times associated with a file to the current server time. | | the times associated with a file to the current server time. | |
| | | | |
| ACE4_DELETE | | ACE4_DELETE | |
| | | | |
| Operation(s) affected: | | Operation(s) affected: | |
| | | | |
| REMOVE | | REMOVE | |
| | | | |
| Discussion: | | Discussion: | |
| | | | |
| skipping to change at page 64, line 34 | | skipping to change at page 67, line 5 | |
| | | | |
| If a server receives a SETATTR request that it cannot accurately | | If a server receives a SETATTR request that it cannot accurately | |
| implement, it should err in the direction of more restricted access, | | implement, it should err in the direction of more restricted access, | |
| except in the previously discussed cases of execute and read. For | | except in the previously discussed cases of execute and read. For | |
| example, suppose a server cannot distinguish overwriting data from | | example, suppose a server cannot distinguish overwriting data from | |
| appending new data, as described in the previous paragraph. If a | | appending new data, as described in the previous paragraph. If a | |
| client submits an ALLOW ACE where ACE4_APPEND_DATA is set but | | client submits an ALLOW ACE where ACE4_APPEND_DATA is set but | |
| ACE4_WRITE_DATA is not (or vice versa), the server should either turn | | ACE4_WRITE_DATA is not (or vice versa), the server should either turn | |
| off ACE4_APPEND_DATA or reject the request with NFS4ERR_ATTRNOTSUPP. | | off ACE4_APPEND_DATA or reject the request with NFS4ERR_ATTRNOTSUPP. | |
| | | | |
|
| 6.2.1.3.2. ACE4_DELETE vs. ACE4_DELETE_CHILD | | 6.2.1.3.2. ACE4_DELETE versus ACE4_DELETE_CHILD | |
| | | | |
| Two access mask bits govern the ability to delete a directory entry: | | Two access mask bits govern the ability to delete a directory entry: | |
|
| ACE4_DELETE on the object itself (the "target"), and | | ACE4_DELETE on the object itself (the "target") and ACE4_DELETE_CHILD | |
| ACE4_DELETE_CHILD on the containing directory (the "parent"). | | on the containing directory (the "parent"). | |
| | | | |
| Many systems also take the "sticky bit" (MODE4_SVTX) on a directory | | Many systems also take the "sticky bit" (MODE4_SVTX) on a directory | |
| to allow unlink only to a user that owns either the target or the | | to allow unlink only to a user that owns either the target or the | |
|
| parent; on some such systems the decision also depends on whether the | | parent; on some such systems, the decision also depends on whether | |
| target is writable. | | the target is writable. | |
| | | | |
| Servers SHOULD allow unlink if either ACE4_DELETE is permitted on the | | Servers SHOULD allow unlink if either ACE4_DELETE is permitted on the | |
|
| target, or ACE4_DELETE_CHILD is permitted on the parent. (Note that | | target or ACE4_DELETE_CHILD is permitted on the parent. (Note that | |
| this is true even if the parent or target explicitly denies the other | | this is true even if the parent or target explicitly denies the other | |
| of these permissions.) | | of these permissions.) | |
| | | | |
| If the ACLs in question neither explicitly ALLOW nor DENY either of | | If the ACLs in question neither explicitly ALLOW nor DENY either of | |
| the above, and if MODE4_SVTX is not set on the parent, then the | | the above, and if MODE4_SVTX is not set on the parent, then the | |
| server SHOULD allow the removal if and only if ACE4_ADD_FILE is | | server SHOULD allow the removal if and only if ACE4_ADD_FILE is | |
| permitted. In the case where MODE4_SVTX is set, the server may also | | permitted. In the case where MODE4_SVTX is set, the server may also | |
| require the remover to own either the parent or the target, or may | | require the remover to own either the parent or the target, or may | |
| require the target to be writable. | | require the target to be writable. | |
| | | | |
|
| This allows servers to support something close to traditional UNIX- | | This allows servers to support something close to traditional | |
| like semantics, with ACE4_ADD_FILE taking the place of the write bit. | | UNIX-like semantics, with ACE4_ADD_FILE taking the place of the | |
| | | write bit. | |
| | | | |
| 6.2.1.4. ACE flag | | 6.2.1.4. ACE flag | |
| | | | |
| The bitmask constants used for the flag field are as follows: | | The bitmask constants used for the flag field are as follows: | |
| | | | |
| const ACE4_FILE_INHERIT_ACE = 0x00000001; | | const ACE4_FILE_INHERIT_ACE = 0x00000001; | |
| const ACE4_DIRECTORY_INHERIT_ACE = 0x00000002; | | const ACE4_DIRECTORY_INHERIT_ACE = 0x00000002; | |
| const ACE4_NO_PROPAGATE_INHERIT_ACE = 0x00000004; | | const ACE4_NO_PROPAGATE_INHERIT_ACE = 0x00000004; | |
| const ACE4_INHERIT_ONLY_ACE = 0x00000008; | | const ACE4_INHERIT_ONLY_ACE = 0x00000008; | |
| const ACE4_SUCCESSFUL_ACCESS_ACE_FLAG = 0x00000010; | | const ACE4_SUCCESSFUL_ACCESS_ACE_FLAG = 0x00000010; | |
| | | | |
| skipping to change at page 65, line 41 | | skipping to change at page 68, line 13 | |
| should reject the request with NFS4ERR_ATTRNOTSUPP. If the server | | should reject the request with NFS4ERR_ATTRNOTSUPP. If the server | |
| supports a single "inherit ACE" flag that applies to both files and | | supports a single "inherit ACE" flag that applies to both files and | |
| directories, the server may reject the request (i.e., requiring the | | directories, the server may reject the request (i.e., requiring the | |
| client to set both the file and directory inheritance flags). The | | client to set both the file and directory inheritance flags). The | |
| server may also accept the request and silently turn on the | | server may also accept the request and silently turn on the | |
| ACE4_DIRECTORY_INHERIT_ACE flag. | | ACE4_DIRECTORY_INHERIT_ACE flag. | |
| | | | |
| 6.2.1.4.1. Discussion of Flag Bits | | 6.2.1.4.1. Discussion of Flag Bits | |
| | | | |
| ACE4_FILE_INHERIT_ACE | | ACE4_FILE_INHERIT_ACE | |
|
| Any non-directory file in any sub-directory will get this ACE | | Any non-directory file in any subdirectory will get this ACE | |
| inherited. | | inherited. | |
| | | | |
| ACE4_DIRECTORY_INHERIT_ACE | | ACE4_DIRECTORY_INHERIT_ACE | |
| Can be placed on a directory and indicates that this ACE should be | | Can be placed on a directory and indicates that this ACE should be | |
| added to each new directory created. | | added to each new directory created. | |
| If this flag is set in an ACE in an ACL attribute to be set on a | | If this flag is set in an ACE in an ACL attribute to be set on a | |
| non-directory file system object, the operation attempting to set | | non-directory file system object, the operation attempting to set | |
| the ACL SHOULD fail with NFS4ERR_ATTRNOTSUPP. | | the ACL SHOULD fail with NFS4ERR_ATTRNOTSUPP. | |
| | | | |
| ACE4_INHERIT_ONLY_ACE | | ACE4_INHERIT_ONLY_ACE | |
| | | | |
| skipping to change at page 66, line 26 | | skipping to change at page 68, line 46 | |
| Can be placed on a directory. This flag tells the server that | | Can be placed on a directory. This flag tells the server that | |
| inheritance of this ACE should stop at newly created child | | inheritance of this ACE should stop at newly created child | |
| directories. | | directories. | |
| | | | |
| ACE4_SUCCESSFUL_ACCESS_ACE_FLAG | | ACE4_SUCCESSFUL_ACCESS_ACE_FLAG | |
| | | | |
| ACE4_FAILED_ACCESS_ACE_FLAG | | ACE4_FAILED_ACCESS_ACE_FLAG | |
| The ACE4_SUCCESSFUL_ACCESS_ACE_FLAG (SUCCESS) and | | The ACE4_SUCCESSFUL_ACCESS_ACE_FLAG (SUCCESS) and | |
| ACE4_FAILED_ACCESS_ACE_FLAG (FAILED) flag bits may be set only on | | ACE4_FAILED_ACCESS_ACE_FLAG (FAILED) flag bits may be set only on | |
| ACE4_SYSTEM_AUDIT_ACE_TYPE (AUDIT) and ACE4_SYSTEM_ALARM_ACE_TYPE | | ACE4_SYSTEM_AUDIT_ACE_TYPE (AUDIT) and ACE4_SYSTEM_ALARM_ACE_TYPE | |
|
| (ALARM) ACE types. If during the processing of the file's ACL, | | (ALARM) ACE types. If, during the processing of the file's ACL, | |
| the server encounters an AUDIT or ALARM ACE that matches the | | the server encounters an AUDIT or ALARM ACE that matches the | |
|
| principal attempting the OPEN, the server notes that fact, and the | | principal attempting the OPEN, the server notes that fact and | |
| presence, if any, of the SUCCESS and FAILED flags encountered in | | notes the presence, if any, of the SUCCESS and FAILED flags | |
| the AUDIT or ALARM ACE. Once the server completes the ACL | | encountered in the AUDIT or ALARM ACE. Once the server completes | |
| processing, it then notes if the operation succeeded or failed. | | the ACL processing, it then notes if the operation succeeded or | |
| If the operation succeeded, and if the SUCCESS flag was set for a | | failed. If the operation succeeded, and if the SUCCESS flag was | |
| matching AUDIT or ALARM ACE, then the appropriate AUDIT or ALARM | | set for a matching AUDIT or ALARM ACE, then the appropriate AUDIT | |
| event occurs. If the operation failed, and if the FAILED flag was | | or ALARM event occurs. If the operation failed, and if the FAILED | |
| set for the matching AUDIT or ALARM ACE, then the appropriate | | flag was set for the matching AUDIT or ALARM ACE, then the | |
| AUDIT or ALARM event occurs. Either or both of the SUCCESS or | | appropriate AUDIT or ALARM event occurs. Either or both of the | |
| FAILED can be set, but if neither is set, the AUDIT or ALARM ACE | | SUCCESS or FAILED can be set, but if neither is set, the AUDIT or | |
| is not useful. | | ALARM ACE is not useful. | |
| | | | |
| The previously described processing applies to ACCESS operations | | The previously described processing applies to ACCESS operations | |
| even when they return NFS4_OK. For the purposes of AUDIT and | | even when they return NFS4_OK. For the purposes of AUDIT and | |
| ALARM, we consider an ACCESS operation to be a "failure" if it | | ALARM, we consider an ACCESS operation to be a "failure" if it | |
| fails to return a bit that was requested and supported. | | fails to return a bit that was requested and supported. | |
| | | | |
| ACE4_IDENTIFIER_GROUP | | ACE4_IDENTIFIER_GROUP | |
| Indicates that the "who" refers to a GROUP as defined under UNIX | | Indicates that the "who" refers to a GROUP as defined under UNIX | |
| or a GROUP ACCOUNT as defined under Windows. Clients and servers | | or a GROUP ACCOUNT as defined under Windows. Clients and servers | |
| MUST ignore the ACE4_IDENTIFIER_GROUP flag on ACEs with a who | | MUST ignore the ACE4_IDENTIFIER_GROUP flag on ACEs with a who | |
| value equal to one of the special identifiers outlined in | | value equal to one of the special identifiers outlined in | |
| Section 6.2.1.5. | | Section 6.2.1.5. | |
| | | | |
| 6.2.1.5. ACE Who | | 6.2.1.5. ACE Who | |
| | | | |
|
| The "who" field of an ACE is an identifier that specifies the | | The who field of an ACE is an identifier that specifies the principal | |
| principal or principals to whom the ACE applies. It may refer to a | | or principals to whom the ACE applies. It may refer to a user or a | |
| user or a group, with the flag bit ACE4_IDENTIFIER_GROUP specifying | | group, with the flag bit ACE4_IDENTIFIER_GROUP specifying which. | |
| which. | | | |
| | | | |
|
| There are several special identifiers which need to be understood | | There are several special identifiers that need to be understood | |
| universally, rather than in the context of a particular DNS domain. | | universally, rather than in the context of a particular DNS domain. | |
| Some of these identifiers cannot be understood when an NFS client | | Some of these identifiers cannot be understood when an NFS client | |
|
| accesses the server, but have meaning when a local process accesses | | accesses the server but have meaning when a local process accesses | |
| the file. The ability to display and modify these permissions is | | the file. The ability to display and modify these permissions is | |
| permitted over NFS, even if none of the access methods on the server | | permitted over NFS, even if none of the access methods on the server | |
|
| understands the identifiers. | | understand the identifiers. | |
| | | | |
| +---------------+---------------------------------------------------+ | | +---------------+---------------------------------------------------+ | |
| | Who | Description | | | | Who | Description | | |
| +---------------+---------------------------------------------------+ | | +---------------+---------------------------------------------------+ | |
| | OWNER | The owner of the file. | | | | OWNER | The owner of the file. | | |
| | GROUP | The group associated with the file. | | | | GROUP | The group associated with the file. | | |
| | EVERYONE | The world, including the owner and owning group. | | | | EVERYONE | The world, including the owner and owning group. | | |
| | INTERACTIVE | Accessed from an interactive terminal. | | | | INTERACTIVE | Accessed from an interactive terminal. | | |
| | NETWORK | Accessed via the network. | | | | NETWORK | Accessed via the network. | | |
| | DIALUP | Accessed as a dialup user to the server. | | | | DIALUP | Accessed as a dialup user to the server. | | |
| | BATCH | Accessed from a batch job. | | | | BATCH | Accessed from a batch job. | | |
| | ANONYMOUS | Accessed without any authentication. | | | | ANONYMOUS | Accessed without any authentication. | | |
| | AUTHENTICATED | Any authenticated user (opposite of ANONYMOUS). | | | | AUTHENTICATED | Any authenticated user (opposite of ANONYMOUS). | | |
| | SERVICE | Access from a system service. | | | | SERVICE | Access from a system service. | | |
| +---------------+---------------------------------------------------+ | | +---------------+---------------------------------------------------+ | |
| | | | |
|
| Table 5 | | Table 5: Special Identifiers | |
| | | | |
| To avoid conflict, these special identifiers are distinguished by an | | To avoid conflict, these special identifiers are distinguished by an | |
| appended "@" and should appear in the form "xxxx@" (with no domain | | appended "@" and should appear in the form "xxxx@" (with no domain | |
|
| name after the "@"). For example: ANONYMOUS@. | | name after the "@") -- for example, ANONYMOUS@. | |
| | | | |
| The ACE4_IDENTIFIER_GROUP flag MUST be ignored on entries with these | | The ACE4_IDENTIFIER_GROUP flag MUST be ignored on entries with these | |
| special identifiers. When encoding entries with these special | | special identifiers. When encoding entries with these special | |
| identifiers, the ACE4_IDENTIFIER_GROUP flag SHOULD be set to zero. | | identifiers, the ACE4_IDENTIFIER_GROUP flag SHOULD be set to zero. | |
| | | | |
| 6.2.1.5.1. Discussion of EVERYONE@ | | 6.2.1.5.1. Discussion of EVERYONE@ | |
| | | | |
| It is important to note that "EVERYONE@" is not equivalent to the | | It is important to note that "EVERYONE@" is not equivalent to the | |
| UNIX "other" entity. This is because, by definition, UNIX "other" | | UNIX "other" entity. This is because, by definition, UNIX "other" | |
| does not include the owner or owning group of a file. "EVERYONE@" | | does not include the owner or owning group of a file. "EVERYONE@" | |
| | | | |
| skipping to change at page 68, line 27 | | skipping to change at page 71, line 12 | |
| const MODE4_WGRP = 0x010; /* write permission: group */ | | const MODE4_WGRP = 0x010; /* write permission: group */ | |
| const MODE4_XGRP = 0x008; /* execute permission: group */ | | const MODE4_XGRP = 0x008; /* execute permission: group */ | |
| const MODE4_ROTH = 0x004; /* read permission: other */ | | const MODE4_ROTH = 0x004; /* read permission: other */ | |
| const MODE4_WOTH = 0x002; /* write permission: other */ | | const MODE4_WOTH = 0x002; /* write permission: other */ | |
| const MODE4_XOTH = 0x001; /* execute permission: other */ | | const MODE4_XOTH = 0x001; /* execute permission: other */ | |
| | | | |
| Bits MODE4_RUSR, MODE4_WUSR, and MODE4_XUSR apply to the principal | | Bits MODE4_RUSR, MODE4_WUSR, and MODE4_XUSR apply to the principal | |
| identified in the owner attribute. Bits MODE4_RGRP, MODE4_WGRP, and | | identified in the owner attribute. Bits MODE4_RGRP, MODE4_WGRP, and | |
| MODE4_XGRP apply to principals identified in the owner_group | | MODE4_XGRP apply to principals identified in the owner_group | |
| attribute but who are not identified in the owner attribute. Bits | | attribute but who are not identified in the owner attribute. Bits | |
|
| MODE4_ROTH, MODE4_WOTH, MODE4_XOTH apply to any principal that does | | MODE4_ROTH, MODE4_WOTH, and MODE4_XOTH apply to any principal that | |
| not match that in the owner attribute, and does not have a group | | does not match that in the owner attribute and does not have a group | |
| matching that of the owner_group attribute. | | matching that of the owner_group attribute. | |
| | | | |
| Bits within the mode other than those specified above are not defined | | Bits within the mode other than those specified above are not defined | |
| by this protocol. A server MUST NOT return bits other than those | | by this protocol. A server MUST NOT return bits other than those | |
| defined above in a GETATTR or READDIR operation, and it MUST return | | defined above in a GETATTR or READDIR operation, and it MUST return | |
| NFS4ERR_INVAL if bits other than those defined above are set in a | | NFS4ERR_INVAL if bits other than those defined above are set in a | |
|
| SETATTR, CREATE, OPEN, VERIFY or NVERIFY operation. | | SETATTR, CREATE, OPEN, VERIFY, or NVERIFY operation. | |
| | | | |
| 6.3. Common Methods | | 6.3. Common Methods | |
| | | | |
| The requirements in this section will be referred to in future | | The requirements in this section will be referred to in future | |
| sections, especially Section 6.4. | | sections, especially Section 6.4. | |
| | | | |
| 6.3.1. Interpreting an ACL | | 6.3.1. Interpreting an ACL | |
| | | | |
| 6.3.1.1. Server Considerations | | 6.3.1.1. Server Considerations | |
| | | | |
| | | | |
| skipping to change at page 69, line 10 | | skipping to change at page 71, line 43 | |
| be the sole determiner of access. For example: | | be the sole determiner of access. For example: | |
| | | | |
| o In the case of a file system exported as read-only, the server may | | o In the case of a file system exported as read-only, the server may | |
| deny write permissions even though an object's ACL grants it. | | deny write permissions even though an object's ACL grants it. | |
| | | | |
| o Server implementations MAY grant ACE4_WRITE_ACL and ACE4_READ_ACL | | o Server implementations MAY grant ACE4_WRITE_ACL and ACE4_READ_ACL | |
| permissions to prevent a situation from arising in which there is | | permissions to prevent a situation from arising in which there is | |
| no valid way to ever modify the ACL. | | no valid way to ever modify the ACL. | |
| | | | |
| o All servers will allow a user the ability to read the data of the | | o All servers will allow a user the ability to read the data of the | |
|
| file when only the execute permission is granted (i.e., If the ACL | | file when only the execute permission is granted (i.e., if the ACL | |
| denies the user the ACE4_READ_DATA access and allows the user | | denies the user ACE4_READ_DATA access and allows the user | |
| ACE4_EXECUTE, the server will allow the user to read the data of | | ACE4_EXECUTE, the server will allow the user to read the data of | |
| the file). | | the file). | |
| | | | |
|
| o Many servers have the notion of owner-override in which the owner | | o Many servers have the notion of owner-override, in which the owner | |
| of the object is allowed to override accesses that are denied by | | of the object is allowed to override accesses that are denied by | |
| the ACL. This may be helpful, for example, to allow users | | the ACL. This may be helpful, for example, to allow users | |
| continued access to open files on which the permissions have | | continued access to open files on which the permissions have | |
| changed. | | changed. | |
| | | | |
| o Many servers have the notion of a "superuser" that has privileges | | o Many servers have the notion of a "superuser" that has privileges | |
| beyond an ordinary user. The superuser may be able to read or | | beyond an ordinary user. The superuser may be able to read or | |
|
| write data or metadata in ways that would not be permitted by the | | write data or metadata in ways that would not be permitted by | |
| ACL. | | the ACL. | |
| | | | |
| 6.3.1.2. Client Considerations | | 6.3.1.2. Client Considerations | |
| | | | |
| Clients SHOULD NOT do their own access checks based on their | | Clients SHOULD NOT do their own access checks based on their | |
|
| interpretation the ACL, but rather use the OPEN and ACCESS operations | | interpretation of the ACL but rather use the OPEN and ACCESS | |
| to do access checks. This allows the client to act on the results of | | operations to do access checks. This allows the client to act on the | |
| having the server determine whether or not access should be granted | | results of having the server determine whether or not access should | |
| based on its interpretation of the ACL. | | be granted based on its interpretation of the ACL. | |
| | | | |
| Clients must be aware of situations in which an object's ACL will | | Clients must be aware of situations in which an object's ACL will | |
| define a certain access even though the server will not have adequate | | define a certain access even though the server will not have adequate | |
| information to enforce it. For example, the server has no way of | | information to enforce it. For example, the server has no way of | |
| determining whether a particular OPEN reflects a user's open for read | | determining whether a particular OPEN reflects a user's open for read | |
|
| access, or is done as part of executing the file in question. In | | access or is done as part of executing the file in question. In such | |
| such situations, the client needs to do its part in the enforcement | | situations, the client needs to do its part in the enforcement of | |
| of access as defined by the ACL. To do this, the client will send | | access as defined by the ACL. To do this, the client will send the | |
| the appropriate ACCESS operation (or use a cached previous | | appropriate ACCESS operation (or use a cached previous determination) | |
| determination) prior to servicing the request of the user or | | prior to servicing the request of the user or application in order to | |
| application in order to determine whether the user or application | | determine whether the user or application should be granted the | |
| should be granted the access requested. For examples in which the | | access requested. For examples in which the ACL may define accesses | |
| ACL may define accesses that the server does not enforce see | | that the server does not enforce, see Section 6.3.1.1. | |
| Section 6.3.1.1. | | | |
| | | | |
|
| 6.3.2. Computing a Mode Attribute from an ACL | | 6.3.2. Computing a mode Attribute from an ACL | |
| | | | |
|
| The following method can be used to calculate the MODE4_R*, MODE4_W* | | The following method can be used to calculate the MODE4_R*, MODE4_W*, | |
| and MODE4_X* bits of a mode attribute, based upon an ACL. | | and MODE4_X* bits of a mode attribute, based upon an ACL. | |
| | | | |
| First, for each of the special identifiers OWNER@, GROUP@, and | | First, for each of the special identifiers OWNER@, GROUP@, and | |
| EVERYONE@, evaluate the ACL in order, considering only ALLOW and DENY | | EVERYONE@, evaluate the ACL in order, considering only ALLOW and DENY | |
| ACEs for the identifier EVERYONE@ and for the identifier under | | ACEs for the identifier EVERYONE@ and for the identifier under | |
| consideration. The result of the evaluation will be an NFSv4 ACL | | consideration. The result of the evaluation will be an NFSv4 ACL | |
| mask showing exactly which bits are permitted to that identifier. | | mask showing exactly which bits are permitted to that identifier. | |
| | | | |
| Then translate the calculated mask for OWNER@, GROUP@, and EVERYONE@ | | Then translate the calculated mask for OWNER@, GROUP@, and EVERYONE@ | |
|
| into mode bits for, respectively, the user, group, and other, as | | into mode bits for the user, group, and other, respectively, as | |
| follows: | | follows: | |
| | | | |
| 1. Set the read bit (MODE4_RUSR, MODE4_RGRP, or MODE4_ROTH) if and | | 1. Set the read bit (MODE4_RUSR, MODE4_RGRP, or MODE4_ROTH) if and | |
| only if ACE4_READ_DATA is set in the corresponding mask. | | only if ACE4_READ_DATA is set in the corresponding mask. | |
| | | | |
| 2. Set the write bit (MODE4_WUSR, MODE4_WGRP, or MODE4_WOTH) if and | | 2. Set the write bit (MODE4_WUSR, MODE4_WGRP, or MODE4_WOTH) if and | |
| only if ACE4_WRITE_DATA and ACE4_APPEND_DATA are both set in the | | only if ACE4_WRITE_DATA and ACE4_APPEND_DATA are both set in the | |
| corresponding mask. | | corresponding mask. | |
| | | | |
| 3. Set the execute bit (MODE4_XUSR, MODE4_XGRP, or MODE4_XOTH), if | | 3. Set the execute bit (MODE4_XUSR, MODE4_XGRP, or MODE4_XOTH), if | |
| | | | |
| skipping to change at page 70, line 46 | | skipping to change at page 73, line 40 | |
| | | | |
| The same user confusion seen when fetching the mode also results if | | The same user confusion seen when fetching the mode also results if | |
| setting the mode does not effectively control permissions for the | | setting the mode does not effectively control permissions for the | |
| owner, group, and other users; this motivates some of the | | owner, group, and other users; this motivates some of the | |
| requirements that follow. | | requirements that follow. | |
| | | | |
| 6.4. Requirements | | 6.4. Requirements | |
| | | | |
| The server that supports both mode and ACL must take care to | | The server that supports both mode and ACL must take care to | |
| synchronize the MODE4_*USR, MODE4_*GRP, and MODE4_*OTH bits with the | | synchronize the MODE4_*USR, MODE4_*GRP, and MODE4_*OTH bits with the | |
|
| ACEs which have respective who fields of "OWNER@", "GROUP@", and | | ACEs that have respective who fields of "OWNER@", "GROUP@", and | |
| "EVERYONE@" so that the client can see semantically equivalent access | | "EVERYONE@" so that the client can see that semantically equivalent | |
| permissions exist whether the client asks for owner, owner_group and | | access permissions exist whether the client asks for just the ACL or | |
| mode attributes, or for just the ACL. | | any of the owner, owner_group, and mode attributes. | |
| | | | |
| Many requirements refer to Section 6.3.2, but note that the methods | | Many requirements refer to Section 6.3.2, but note that the methods | |
| have behaviors specified with "SHOULD". This is intentional, to | | have behaviors specified with "SHOULD". This is intentional, to | |
| avoid invalidating existing implementations that compute the mode | | avoid invalidating existing implementations that compute the mode | |
| according to the withdrawn POSIX ACL draft ([P1003.1e]), rather than | | according to the withdrawn POSIX ACL draft ([P1003.1e]), rather than | |
| by actual permissions on owner, group, and other. | | by actual permissions on owner, group, and other. | |
| | | | |
| 6.4.1. Setting the mode and/or ACL Attributes | | 6.4.1. Setting the mode and/or ACL Attributes | |
| | | | |
|
| 6.4.1.1. Setting mode and not ACL | | 6.4.1.1. Setting mode and Not ACL | |
| | | | |
| When any of the nine low-order mode bits are changed because the mode | | When any of the nine low-order mode bits are changed because the mode | |
| attribute was set, and no ACL attribute is explicitly set, the acl | | attribute was set, and no ACL attribute is explicitly set, the acl | |
| attribute must be modified in accordance with the updated value of | | attribute must be modified in accordance with the updated value of | |
| those bits. This must happen even if the value of the low-order bits | | those bits. This must happen even if the value of the low-order bits | |
| is the same after the mode is set as before. | | is the same after the mode is set as before. | |
| | | | |
| Note that any AUDIT or ALARM ACEs are unaffected by changes to the | | Note that any AUDIT or ALARM ACEs are unaffected by changes to the | |
| mode. | | mode. | |
| | | | |
| In cases in which the permissions bits are subject to change, the acl | | In cases in which the permissions bits are subject to change, the acl | |
| attribute MUST be modified such that the mode computed via the method | | attribute MUST be modified such that the mode computed via the method | |
|
| in Section 6.3.2 yields the low-order nine bits (MODE4_R*, MODE4_W*, | | described in Section 6.3.2 yields the low-order nine bits (MODE4_R*, | |
| MODE4_X*) of the mode attribute as modified by the attribute change. | | MODE4_W*, MODE4_X*) of the mode attribute as modified by the change | |
| The ACL attributes SHOULD also be modified such that: | | attribute. The ACL attributes SHOULD also be modified such that: | |
| | | | |
| 1. If MODE4_RGRP is not set, entities explicitly listed in the ACL | | 1. If MODE4_RGRP is not set, entities explicitly listed in the ACL | |
| other than OWNER@ and EVERYONE@ SHOULD NOT be granted | | other than OWNER@ and EVERYONE@ SHOULD NOT be granted | |
| ACE4_READ_DATA. | | ACE4_READ_DATA. | |
| | | | |
| 2. If MODE4_WGRP is not set, entities explicitly listed in the ACL | | 2. If MODE4_WGRP is not set, entities explicitly listed in the ACL | |
| other than OWNER@ and EVERYONE@ SHOULD NOT be granted | | other than OWNER@ and EVERYONE@ SHOULD NOT be granted | |
| ACE4_WRITE_DATA or ACE4_APPEND_DATA. | | ACE4_WRITE_DATA or ACE4_APPEND_DATA. | |
| | | | |
| 3. If MODE4_XGRP is not set, entities explicitly listed in the ACL | | 3. If MODE4_XGRP is not set, entities explicitly listed in the ACL | |
| other than OWNER@ and EVERYONE@ SHOULD NOT be granted | | other than OWNER@ and EVERYONE@ SHOULD NOT be granted | |
| ACE4_EXECUTE. | | ACE4_EXECUTE. | |
| | | | |
| Access mask bits other than those listed above, appearing in ALLOW | | Access mask bits other than those listed above, appearing in ALLOW | |
| ACEs, MAY also be disabled. | | ACEs, MAY also be disabled. | |
| | | | |
| Note that ACEs with the flag ACE4_INHERIT_ONLY_ACE set do not affect | | Note that ACEs with the flag ACE4_INHERIT_ONLY_ACE set do not affect | |
|
| the permissions of the ACL itself, nor do ACEs of the type AUDIT and | | the permissions of the ACL itself, nor do ACEs of the types AUDIT and | |
| ALARM. As such, it is desirable to leave these ACEs unmodified when | | ALARM. As such, it is desirable to leave these ACEs unmodified when | |
| modifying the ACL attributes. | | modifying the ACL attributes. | |
| | | | |
| Also note that the requirement may be met by discarding the acl in | | Also note that the requirement may be met by discarding the acl in | |
| favor of an ACL that represents the mode and only the mode. This is | | favor of an ACL that represents the mode and only the mode. This is | |
| permitted, but it is preferable for a server to preserve as much of | | permitted, but it is preferable for a server to preserve as much of | |
| the ACL as possible without violating the above requirements. | | the ACL as possible without violating the above requirements. | |
|
| | | | |
| Discarding the ACL makes it effectively impossible for a file created | | Discarding the ACL makes it effectively impossible for a file created | |
| with a mode attribute to inherit an ACL (see Section 6.4.3). | | with a mode attribute to inherit an ACL (see Section 6.4.3). | |
| | | | |
|
| 6.4.1.2. Setting ACL and not mode | | 6.4.1.2. Setting ACL and Not mode | |
| | | | |
| When setting the acl and not setting the mode attribute, the | | When setting the acl and not setting the mode attribute, the | |
| permission bits of the mode need to be derived from the ACL. In this | | permission bits of the mode need to be derived from the ACL. In this | |
| case, the ACL attribute SHOULD be set as given. The nine low-order | | case, the ACL attribute SHOULD be set as given. The nine low-order | |
| bits of the mode attribute (MODE4_R*, MODE4_W*, MODE4_X*) MUST be | | bits of the mode attribute (MODE4_R*, MODE4_W*, MODE4_X*) MUST be | |
|
| modified to match the result of the method Section 6.3.2. The three | | modified to match the result of the method described in | |
| high-order bits of the mode (MODE4_SUID, MODE4_SGID, MODE4_SVTX) | | Section 6.3.2. The three high-order bits of the mode (MODE4_SUID, | |
| SHOULD remain unchanged. | | MODE4_SGID, MODE4_SVTX) SHOULD remain unchanged. | |
| | | | |
|
| 6.4.1.3. Setting both ACL and mode | | 6.4.1.3. Setting Both ACL and mode | |
| | | | |
| When setting both the mode and the acl attribute in the same | | When setting both the mode and the acl attribute in the same | |
| operation, the attributes MUST be applied in this order: mode, then | | operation, the attributes MUST be applied in this order: mode, then | |
| ACL. The mode-related attribute is set as given, then the ACL | | ACL. The mode-related attribute is set as given, then the ACL | |
| attribute is set as given, possibly changing the final mode, as | | attribute is set as given, possibly changing the final mode, as | |
| described above in Section 6.4.1.2. | | described above in Section 6.4.1.2. | |
| | | | |
| 6.4.2. Retrieving the mode and/or ACL Attributes | | 6.4.2. Retrieving the mode and/or ACL Attributes | |
| | | | |
| This section applies only to servers that support both the mode and | | This section applies only to servers that support both the mode and | |
| | | | |
| skipping to change at page 72, line 41 | | skipping to change at page 75, line 38 | |
| Some server implementations may have a concept of "objects without | | Some server implementations may have a concept of "objects without | |
| ACLs", meaning that all permissions are granted and denied according | | ACLs", meaning that all permissions are granted and denied according | |
| to the mode attribute, and that no ACL attribute is stored for that | | to the mode attribute, and that no ACL attribute is stored for that | |
| object. If an ACL attribute is requested of such a server, the | | object. If an ACL attribute is requested of such a server, the | |
| server SHOULD return an ACL that does not conflict with the mode; | | server SHOULD return an ACL that does not conflict with the mode; | |
| that is to say, the ACL returned SHOULD represent the nine low-order | | that is to say, the ACL returned SHOULD represent the nine low-order | |
| bits of the mode attribute (MODE4_R*, MODE4_W*, MODE4_X*) as | | bits of the mode attribute (MODE4_R*, MODE4_W*, MODE4_X*) as | |
| described in Section 6.3.2. | | described in Section 6.3.2. | |
| | | | |
| For other server implementations, the ACL attribute is always present | | For other server implementations, the ACL attribute is always present | |
|
| for every object. Such servers SHOULD store at least the three high- | | for every object. Such servers SHOULD store at least the three | |
| order bits of the mode attribute (MODE4_SUID, MODE4_SGID, | | high-order bits of the mode attribute (MODE4_SUID, MODE4_SGID, | |
| MODE4_SVTX). The server SHOULD return a mode attribute if one is | | MODE4_SVTX). The server SHOULD return a mode attribute if one is | |
| requested, and the low-order nine bits of the mode (MODE4_R*, | | requested, and the low-order nine bits of the mode (MODE4_R*, | |
| MODE4_W*, MODE4_X*) MUST match the result of applying the method in | | MODE4_W*, MODE4_X*) MUST match the result of applying the method in | |
| Section 6.3.2 to the ACL attribute. | | Section 6.3.2 to the ACL attribute. | |
| | | | |
| 6.4.3. Creating New Objects | | 6.4.3. Creating New Objects | |
| | | | |
| If a server supports any ACL attributes, it may use the ACL | | If a server supports any ACL attributes, it may use the ACL | |
| attributes on the parent directory to compute an initial ACL | | attributes on the parent directory to compute an initial ACL | |
| attribute for a newly created object. This will be referred to as | | attribute for a newly created object. This will be referred to as | |
| | | | |
| skipping to change at page 73, line 22 | | skipping to change at page 76, line 21 | |
| 1. If just the mode is given in the call: | | 1. If just the mode is given in the call: | |
| | | | |
| In this case, inheritance SHOULD take place, but the mode MUST be | | In this case, inheritance SHOULD take place, but the mode MUST be | |
| applied to the inherited ACL as described in Section 6.4.1.1, | | applied to the inherited ACL as described in Section 6.4.1.1, | |
| thereby modifying the ACL. | | thereby modifying the ACL. | |
| | | | |
| 2. If just the ACL is given in the call: | | 2. If just the ACL is given in the call: | |
| | | | |
| In this case, inheritance SHOULD NOT take place, and the ACL as | | In this case, inheritance SHOULD NOT take place, and the ACL as | |
| defined in the CREATE or OPEN will be set without modification, | | defined in the CREATE or OPEN will be set without modification, | |
|
| and the mode modified as in Section 6.4.1.2 | | and the mode modified as in Section 6.4.1.2. | |
| | | | |
| 3. If both mode and ACL are given in the call: | | 3. If both mode and ACL are given in the call: | |
| | | | |
| In this case, inheritance SHOULD NOT take place, and both | | In this case, inheritance SHOULD NOT take place, and both | |
| attributes will be set as described in Section 6.4.1.3. | | attributes will be set as described in Section 6.4.1.3. | |
| | | | |
|
| 4. If neither mode nor ACL are given in the call: | | 4. If neither mode nor ACL is given in the call: | |
| | | | |
| In the case where an object is being created without any initial | | In the case where an object is being created without any initial | |
| attributes at all, e.g., an OPEN operation with an opentype4 of | | attributes at all, e.g., an OPEN operation with an opentype4 of | |
| OPEN4_CREATE and a createmode4 of EXCLUSIVE4, inheritance SHOULD | | OPEN4_CREATE and a createmode4 of EXCLUSIVE4, inheritance SHOULD | |
| NOT take place. Instead, the server SHOULD set permissions to | | NOT take place. Instead, the server SHOULD set permissions to | |
| deny all access to the newly created object. It is expected that | | deny all access to the newly created object. It is expected that | |
| the appropriate client will set the desired attributes in a | | the appropriate client will set the desired attributes in a | |
| subsequent SETATTR operation, and the server SHOULD allow that | | subsequent SETATTR operation, and the server SHOULD allow that | |
| operation to succeed, regardless of what permissions the object | | operation to succeed, regardless of what permissions the object | |
| is created with. For example, an empty ACL denies all | | is created with. For example, an empty ACL denies all | |
| permissions, but the server should allow the owner's SETATTR to | | permissions, but the server should allow the owner's SETATTR to | |
| succeed even though WRITE_ACL is implicitly denied. | | succeed even though WRITE_ACL is implicitly denied. | |
| | | | |
| In other cases, inheritance SHOULD take place, and no | | In other cases, inheritance SHOULD take place, and no | |
| modifications to the ACL will happen. The mode attribute, if | | modifications to the ACL will happen. The mode attribute, if | |
|
| supported, MUST be as computed in Section 6.3.2, with the | | supported, MUST be as computed via the method described in | |
| MODE4_SUID, MODE4_SGID and MODE4_SVTX bits clear. If no | | Section 6.3.2, with the MODE4_SUID, MODE4_SGID, and MODE4_SVTX | |
| inheritable ACEs exist on the parent directory, the rules for | | bits clear. If no inheritable ACEs exist on the parent | |
| creating acl attributes are implementation defined. | | directory, the rules for creating acl attributes are | |
| | | implementation defined. | |
| | | | |
| 6.4.3.1. The Inherited ACL | | 6.4.3.1. The Inherited ACL | |
| | | | |
| If the object being created is not a directory, the inherited ACL | | If the object being created is not a directory, the inherited ACL | |
| SHOULD NOT inherit ACEs from the parent directory ACL unless the | | SHOULD NOT inherit ACEs from the parent directory ACL unless the | |
| ACE4_FILE_INHERIT_FLAG is set. | | ACE4_FILE_INHERIT_FLAG is set. | |
| | | | |
| If the object being created is a directory, the inherited ACL should | | If the object being created is a directory, the inherited ACL should | |
|
| inherit all inheritable ACEs from the parent directory, those that | | inherit all inheritable ACEs from the parent directory, i.e., those | |
| have ACE4_FILE_INHERIT_ACE or ACE4_DIRECTORY_INHERIT_ACE flag set. | | that have the ACE4_FILE_INHERIT_ACE or ACE4_DIRECTORY_INHERIT_ACE | |
| If the inheritable ACE has ACE4_FILE_INHERIT_ACE set, but | | flag set. If the inheritable ACE has ACE4_FILE_INHERIT_ACE set, but | |
| ACE4_DIRECTORY_INHERIT_ACE is clear, the inherited ACE on the newly | | ACE4_DIRECTORY_INHERIT_ACE is clear, the inherited ACE on the newly | |
| created directory MUST have the ACE4_INHERIT_ONLY_ACE flag set to | | created directory MUST have the ACE4_INHERIT_ONLY_ACE flag set to | |
|
| prevent the directory from being affected by ACEs meant for non- | | prevent the directory from being affected by ACEs meant for | |
| directories. | | non-directories. | |
| | | | |
| When a new directory is created, the server MAY split any inherited | | When a new directory is created, the server MAY split any inherited | |
|
| ACE which is both inheritable and effective (in other words, which | | ACE that is both inheritable and effective (in other words, that has | |
| has neither ACE4_INHERIT_ONLY_ACE nor ACE4_NO_PROPAGATE_INHERIT_ACE | | neither ACE4_INHERIT_ONLY_ACE nor ACE4_NO_PROPAGATE_INHERIT_ACE set) | |
| set), into two ACEs, one with no inheritance flags, and one with | | into two ACEs -- one with no inheritance flags, and one with | |
| ACE4_INHERIT_ONLY_ACE set. This makes it simpler to modify the | | ACE4_INHERIT_ONLY_ACE set. This makes it simpler to modify the | |
|
| effective permissions on the directory without modifying the ACE | | effective permissions on the directory without modifying the ACE that | |
| which is to be inherited to the new directory's children. | | is to be inherited to the new directory's children. | |
| | | | |
|
| 7. NFS Server Name Space | | 7. NFS Server Namespace | |
| | | | |
| 7.1. Server Exports | | 7.1. Server Exports | |
| | | | |
|
| On a UNIX server the name space describes all the files reachable by | | On a UNIX server, the namespace describes all the files reachable by | |
| pathnames under the root directory or "/". On a Windows server the | | pathnames under the root directory or "/". On a Windows server, the | |
| name space constitutes all the files on disks named by mapped disk | | namespace constitutes all the files on disks named by mapped disk | |
| letters. NFS server administrators rarely make the entire server's | | letters. NFS server administrators rarely make the entire server's | |
|
| file system name space available to NFS clients. More often portions | | file system namespace available to NFS clients. More often, portions | |
| of the name space are made available via an "export" feature. In | | of the namespace are made available via an "export" feature. In | |
| previous versions of the NFS protocol, the root filehandle for each | | previous versions of the NFS protocol, the root filehandle for each | |
| export is obtained through the MOUNT protocol; the client sends a | | export is obtained through the MOUNT protocol; the client sends a | |
|
| string that identifies an object in the exported name space and the | | string that identifies an object in the exported namespace, and the | |
| server returns the root filehandle for it. The MOUNT protocol | | server returns the root filehandle for it. The MOUNT protocol | |
| supports an EXPORTS procedure that will enumerate the server's | | supports an EXPORTS procedure that will enumerate the server's | |
| exports. | | exports. | |
| | | | |
| 7.2. Browsing Exports | | 7.2. Browsing Exports | |
| | | | |
| The NFSv4 protocol provides a root filehandle that clients can use to | | The NFSv4 protocol provides a root filehandle that clients can use to | |
| obtain filehandles for these exports via a multi-component LOOKUP. A | | obtain filehandles for these exports via a multi-component LOOKUP. A | |
| common user experience is to use a graphical user interface (perhaps | | common user experience is to use a graphical user interface (perhaps | |
| a file "Open" dialog window) to find a file via progressive browsing | | a file "Open" dialog window) to find a file via progressive browsing | |
| through a directory tree. The client must be able to move from one | | through a directory tree. The client must be able to move from one | |
| export to another export via single-component, progressive LOOKUP | | export to another export via single-component, progressive LOOKUP | |
| operations. | | operations. | |
| | | | |
| This style of browsing is not well supported by the NFSv2 and NFSv3 | | This style of browsing is not well supported by the NFSv2 and NFSv3 | |
| protocols. The client expects all LOOKUP operations to remain within | | protocols. The client expects all LOOKUP operations to remain within | |
|
| a single server file system. For example, the device attribute will | | a single-server file system. For example, the device attribute will | |
| not change. This prevents a client from taking name space paths that | | not change. This prevents a client from taking namespace paths that | |
| span exports. | | span exports. | |
| | | | |
| An automounter on the client can obtain a snapshot of the server's | | An automounter on the client can obtain a snapshot of the server's | |
|
| name space using the EXPORTS procedure of the MOUNT protocol. If it | | namespace using the EXPORTS procedure of the MOUNT protocol. If it | |
| understands the server's pathname syntax, it can create an image of | | understands the server's pathname syntax, it can create an image of | |
|
| the server's name space on the client. The parts of the name space | | the server's namespace on the client. The parts of the namespace | |
| that are not exported by the server are filled in with a "pseudo file | | that are not exported by the server are filled in with a "pseudo-file | |
| system" that allows the user to browse from one mounted file system | | system" that allows the user to browse from one mounted file system | |
| to another. There is a drawback to this representation of the | | to another. There is a drawback to this representation of the | |
|
| server's name space on the client: it is static. If the server | | server's namespace on the client: it is static. If the server | |
| administrator adds a new export the client will be unaware of it. | | administrator adds a new export, the client will be unaware of it. | |
| | | | |
|
| 7.3. Server Pseudo Filesystem | | 7.3. Server Pseudo-File System | |
| | | | |
|
| NFSv4 servers avoid this name space inconsistency by presenting all | | NFSv4 servers avoid this namespace inconsistency by presenting all | |
| the exports within the framework of a single server name space. An | | the exports within the framework of a single-server namespace. An | |
| NFSv4 client uses LOOKUP and READDIR operations to browse seamlessly | | NFSv4 client uses LOOKUP and READDIR operations to browse seamlessly | |
|
| from one export to another. Portions of the server name space that | | from one export to another. Portions of the server namespace that | |
| are not exported are bridged via a "pseudo file system" that provides | | are not exported are bridged via a "pseudo-file system" that provides | |
| a view of exported directories only. A pseudo file system has a | | a view of exported directories only. A pseudo-file system has a | |
| unique fsid and behaves like a normal, read only file system. | | unique fsid and behaves like a normal, read-only file system. | |
| | | | |
|
| Based on the construction of the server's name space, it is possible | | Based on the construction of the server's namespace, it is possible | |
| that multiple pseudo file systems may exist. For example, | | that multiple pseudo-file systems may exist. For example: | |
| | | | |
|
| /a pseudo file system | | /a pseudo-file system | |
| /a/b real file system | | /a/b real file system | |
|
| /a/b/c pseudo file system | | /a/b/c pseudo-file system | |
| /a/b/c/d real file system | | /a/b/c/d real file system | |
| | | | |
|
| Each of the pseudo file systems are considered separate entities and | | Each of the pseudo-file systems are considered separate entities and | |
| therefore will have a unique fsid. | | therefore will have a unique fsid. | |
| | | | |
| 7.4. Multiple Roots | | 7.4. Multiple Roots | |
| | | | |
| The DOS and Windows operating environments are sometimes described as | | The DOS and Windows operating environments are sometimes described as | |
|
| having "multiple roots". Filesystems are commonly represented as | | having "multiple roots". File systems are commonly represented as | |
| disk letters. MacOS represents file systems as top level names. | | disk letters. MacOS represents file systems as top-level names. | |
| NFSv4 servers for these platforms can construct a pseudo file system | | NFSv4 servers for these platforms can construct a pseudo-file system | |
| above these root names so that disk letters or volume names are | | above these root names so that disk letters or volume names are | |
|
| simply directory names in the pseudo root. | | simply directory names in the pseudo-root. | |
| | | | |
| 7.5. Filehandle Volatility | | 7.5. Filehandle Volatility | |
| | | | |
|
| The nature of the server's pseudo file system is that it is a logical | | The nature of the server's pseudo-file system is that it is a logical | |
| representation of file system(s) available from the server. | | representation of file system(s) available from the server. | |
|
| Therefore, the pseudo file system is most likely constructed | | Therefore, the pseudo-file system is most likely constructed | |
| dynamically when the server is first instantiated. It is expected | | dynamically when the server is first instantiated. It is expected | |
|
| that the pseudo file system may not have an on disk counterpart from | | that the pseudo-file system may not have an on-disk counterpart from | |
| which persistent filehandles could be constructed. Even though it is | | which persistent filehandles could be constructed. Even though it is | |
| preferable that the server provide persistent filehandles for the | | preferable that the server provide persistent filehandles for the | |
|
| pseudo file system, the NFS client should expect that pseudo file | | pseudo-file system, the NFS client should expect that pseudo-file | |
| system filehandles are volatile. This can be confirmed by checking | | system filehandles are volatile. This can be confirmed by checking | |
| the associated "fh_expire_type" attribute for those filehandles in | | the associated "fh_expire_type" attribute for those filehandles in | |
| question. If the filehandles are volatile, the NFS client must be | | question. If the filehandles are volatile, the NFS client must be | |
| prepared to recover a filehandle value (e.g., with a multi-component | | prepared to recover a filehandle value (e.g., with a multi-component | |
| LOOKUP) when receiving an error of NFS4ERR_FHEXPIRED. | | LOOKUP) when receiving an error of NFS4ERR_FHEXPIRED. | |
| | | | |
| 7.6. Exported Root | | 7.6. Exported Root | |
| | | | |
| If the server's root file system is exported, one might conclude that | | If the server's root file system is exported, one might conclude that | |
|
| a pseudo file system is not needed. This would be wrong. Assume the | | a pseudo-file system is not needed. This would be wrong. Assume the | |
| following file systems on a server: | | following file systems on a server: | |
| | | | |
| / disk1 (exported) | | / disk1 (exported) | |
| /a disk2 (not exported) | | /a disk2 (not exported) | |
| /a/b disk3 (exported) | | /a/b disk3 (exported) | |
| | | | |
| Because disk2 is not exported, disk3 cannot be reached with simple | | Because disk2 is not exported, disk3 cannot be reached with simple | |
|
| LOOKUPs. The server must bridge the gap with a pseudo file system. | | LOOKUPs. The server must bridge the gap with a pseudo-file system. | |
| | | | |
| 7.7. Mount Point Crossing | | 7.7. Mount Point Crossing | |
| | | | |
| The server file system environment may be constructed in such a way | | The server file system environment may be constructed in such a way | |
|
| that one file system contains a directory which is 'covered' or | | that one file system contains a directory that is 'covered' or | |
| mounted upon by a second file system. For example: | | mounted upon by a second file system. For example: | |
| | | | |
| /a/b (file system 1) | | /a/b (file system 1) | |
| /a/b/c/d (file system 2) | | /a/b/c/d (file system 2) | |
| | | | |
|
| The pseudo file system for this server may be constructed to look | | The pseudo-file system for this server may be constructed to | |
| like: | | look like: | |
| | | | |
|
| / (place holder/not exported) | | / (placeholder/not exported) | |
| /a/b (file system 1) | | /a/b (file system 1) | |
| /a/b/c/d (file system 2) | | /a/b/c/d (file system 2) | |
| | | | |
|
| It is the server's responsibility to present the pseudo file system | | It is the server's responsibility to present the pseudo-file system | |
| that is complete to the client. If the client sends a lookup request | | that is complete to the client. If the client sends a LOOKUP request | |
| for the path "/a/b/c/d", the server's response is the filehandle of | | for the path "/a/b/c/d", the server's response is the filehandle of | |
| the file system "/a/b/c/d". In previous versions of the NFS | | the file system "/a/b/c/d". In previous versions of the NFS | |
|
| protocol, the server would respond with the filehandle of directory " | | protocol, the server would respond with the filehandle of directory | |
| /a/b/c/d" within the file system "/a/b". | | "/a/b/c/d" within the file system "/a/b". | |
| | | | |
| The NFS client will be able to determine if it crosses a server mount | | The NFS client will be able to determine if it crosses a server mount | |
| point by a change in the value of the "fsid" attribute. | | point by a change in the value of the "fsid" attribute. | |
| | | | |
|
| 7.8. Security Policy and Name Space Presentation | | 7.8. Security Policy and Namespace Presentation | |
| | | | |
| Because NFSv4 clients possess the ability to change the security | | Because NFSv4 clients possess the ability to change the security | |
| mechanisms used, after determining what is allowed, by using SECINFO | | mechanisms used, after determining what is allowed, by using SECINFO | |
| the server SHOULD NOT present a different view of the namespace based | | the server SHOULD NOT present a different view of the namespace based | |
| on the security mechanism being used by a client. Instead, it should | | on the security mechanism being used by a client. Instead, it should | |
| present a consistent view and return NFS4ERR_WRONGSEC if an attempt | | present a consistent view and return NFS4ERR_WRONGSEC if an attempt | |
| is made to access data with an inappropriate security mechanism. | | is made to access data with an inappropriate security mechanism. | |
| | | | |
| If security considerations make it necessary to hide the existence of | | If security considerations make it necessary to hide the existence of | |
| a particular file system, as opposed to all of the data within it, | | a particular file system, as opposed to all of the data within it, | |
| the server can apply the security policy of a shared resource in the | | the server can apply the security policy of a shared resource in the | |
| server's namespace to components of the resource's ancestors. For | | server's namespace to components of the resource's ancestors. For | |
| example: | | example: | |
| | | | |
|
| / (place holder/not exported) | | / (placeholder/not exported) | |
| /a/b (file system 1) | | /a/b (file system 1) | |
| /a/b/MySecretProject (file system 2) | | /a/b/MySecretProject (file system 2) | |
| | | | |
| The /a/b/MySecretProject directory is a real file system and is the | | The /a/b/MySecretProject directory is a real file system and is the | |
| shared resource. Suppose the security policy for /a/b/ | | shared resource. Suppose the security policy for /a/b/ | |
| MySecretProject is Kerberos with integrity and it is desired to limit | | MySecretProject is Kerberos with integrity and it is desired to limit | |
| knowledge of the existence of this file system. In this case, the | | knowledge of the existence of this file system. In this case, the | |
| server should apply the same security policy to /a/b. This allows | | server should apply the same security policy to /a/b. This allows | |
| for knowledge of the existence of a file system to be secured when | | for knowledge of the existence of a file system to be secured when | |
| desirable. | | desirable. | |
| | | | |
| skipping to change at page 78, line 11 | | skipping to change at page 81, line 12 | |
| the server's resources, applying that sort of policy would result in | | the server's resources, applying that sort of policy would result in | |
| the higher-level file system not being accessible using any security | | the higher-level file system not being accessible using any security | |
| flavor. Therefore, that sort of configuration is not compatible with | | flavor. Therefore, that sort of configuration is not compatible with | |
| hiding the existence (as opposed to the contents) from clients using | | hiding the existence (as opposed to the contents) from clients using | |
| multiple disjoint sets of security flavors. | | multiple disjoint sets of security flavors. | |
| | | | |
| In other circumstances, a desirable policy is for the security of a | | In other circumstances, a desirable policy is for the security of a | |
| particular object in the server's namespace to include the union of | | particular object in the server's namespace to include the union of | |
| all security mechanisms of all direct descendants. A common and | | all security mechanisms of all direct descendants. A common and | |
| convenient practice, unless strong security requirements dictate | | convenient practice, unless strong security requirements dictate | |
|
| otherwise, is to make the entire pseudo file system accessible by all | | otherwise, is to make the entire pseudo-file system accessible by all | |
| of the valid security mechanisms. | | of the valid security mechanisms. | |
| | | | |
| Where there is concern about the security of data on the network, | | Where there is concern about the security of data on the network, | |
|
| clients should use strong security mechanisms to access the pseudo | | clients should use strong security mechanisms to access the | |
| file system in order to prevent man-in-the-middle attacks. | | pseudo-file system in order to prevent man-in-the-middle attacks. | |
| | | | |
| 8. Multi-Server Namespace | | 8. Multi-Server Namespace | |
| | | | |
| NFSv4 supports attributes that allow a namespace to extend beyond the | | NFSv4 supports attributes that allow a namespace to extend beyond the | |
| boundaries of a single server. It is RECOMMENDED that clients and | | boundaries of a single server. It is RECOMMENDED that clients and | |
| servers support construction of such multi-server namespaces. Use of | | servers support construction of such multi-server namespaces. Use of | |
| such multi-server namespaces is optional, however, and for many | | such multi-server namespaces is optional, however, and for many | |
| purposes, single-server namespaces are perfectly acceptable. Use of | | purposes, single-server namespaces are perfectly acceptable. Use of | |
| multi-server namespaces can provide many advantages, however, by | | multi-server namespaces can provide many advantages, however, by | |
| separating a file system's logical position in a namespace from the | | separating a file system's logical position in a namespace from the | |
| (possibly changing) logistical and administrative considerations that | | (possibly changing) logistical and administrative considerations that | |
| result in particular file systems being located on particular | | result in particular file systems being located on particular | |
| servers. | | servers. | |
| | | | |
| 8.1. Location Attributes | | 8.1. Location Attributes | |
| | | | |
| NFSv4 contains RECOMMENDED attributes that allow file systems on one | | NFSv4 contains RECOMMENDED attributes that allow file systems on one | |
| server to be associated with one or more instances of that file | | server to be associated with one or more instances of that file | |
| system on other servers. These attributes specify such file system | | system on other servers. These attributes specify such file system | |
|
| instances by specifying a server address target (either as a DNS name | | instances by specifying a server address target (as either a DNS name | |
| representing one or more IP addresses or as a literal IP address) | | representing one or more IP addresses, or a literal IP address), | |
| together with the path of that file system within the associated | | together with the path of that file system within the associated | |
| single-server namespace. | | single-server namespace. | |
| | | | |
| The fs_locations RECOMMENDED attribute allows specification of the | | The fs_locations RECOMMENDED attribute allows specification of the | |
| file system locations where the data corresponding to a given file | | file system locations where the data corresponding to a given file | |
| system may be found. | | system may be found. | |
| | | | |
| 8.2. File System Presence or Absence | | 8.2. File System Presence or Absence | |
| | | | |
| A given location in an NFSv4 namespace (typically but not necessarily | | A given location in an NFSv4 namespace (typically but not necessarily | |
| | | | |
| skipping to change at page 80, line 7 | | skipping to change at page 83, line 13 | |
| information, as discussed below. | | information, as discussed below. | |
| | | | |
| 8.3. Getting Attributes for an Absent File System | | 8.3. Getting Attributes for an Absent File System | |
| | | | |
| When a file system is absent, most attributes are not available, but | | When a file system is absent, most attributes are not available, but | |
| it is necessary to allow the client access to the small set of | | it is necessary to allow the client access to the small set of | |
| attributes that are available, and most particularly that which gives | | attributes that are available, and most particularly that which gives | |
| information about the correct current locations for this file system, | | information about the correct current locations for this file system, | |
| fs_locations. | | fs_locations. | |
| | | | |
|
| 8.3.1. GETATTR Within an Absent File System | | 8.3.1. GETATTR within an Absent File System | |
| | | | |
| As mentioned above, an exception is made for GETATTR in that | | As mentioned above, an exception is made for GETATTR in that | |
| attributes may be obtained for a filehandle within an absent file | | attributes may be obtained for a filehandle within an absent file | |
| system. This exception only applies if the attribute mask contains | | system. This exception only applies if the attribute mask contains | |
|
| at least the fs_locations attribute bit, which indicates the client | | at least the fs_locations attribute bit, which indicates that the | |
| is interested in a result regarding an absent file system. If it is | | client is interested in a result regarding an absent file system. If | |
| not requested, GETATTR will result in an NFS4ERR_MOVED error. | | it is not requested, GETATTR will result in an NFS4ERR_MOVED error. | |
| | | | |
| When a GETATTR is done on an absent file system, the set of supported | | When a GETATTR is done on an absent file system, the set of supported | |
| attributes is very limited. Many attributes, including those that | | attributes is very limited. Many attributes, including those that | |
| are normally REQUIRED, will not be available on an absent file | | are normally REQUIRED, will not be available on an absent file | |
| system. In addition to the fs_locations attribute, the following | | system. In addition to the fs_locations attribute, the following | |
| attributes SHOULD be available on absent file systems. In the case | | attributes SHOULD be available on absent file systems. In the case | |
| of RECOMMENDED attributes, they should be available at least to the | | of RECOMMENDED attributes, they should be available at least to the | |
| same degree that they are available on present file systems. | | same degree that they are available on present file systems. | |
| | | | |
| fsid: This attribute should be provided so that the client can | | fsid: This attribute should be provided so that the client can | |
| | | | |
| skipping to change at page 80, line 41 | | skipping to change at page 83, line 47 | |
| mounted_on_fileid: For objects at the top of an absent file system, | | mounted_on_fileid: For objects at the top of an absent file system, | |
| this attribute needs to be available. Since the fileid is within | | this attribute needs to be available. Since the fileid is within | |
| the present parent file system, there should be no need to | | the present parent file system, there should be no need to | |
| reference the absent file system to provide this information. | | reference the absent file system to provide this information. | |
| | | | |
| Other attributes SHOULD NOT be made available for absent file | | Other attributes SHOULD NOT be made available for absent file | |
| systems, even when it is possible to provide them. The server should | | systems, even when it is possible to provide them. The server should | |
| not assume that more information is always better and should avoid | | not assume that more information is always better and should avoid | |
| gratuitously providing additional information. | | gratuitously providing additional information. | |
| | | | |
|
| When a GETATTR operation includes a bit mask for the attribute | | When a GETATTR operation includes a bitmask for the attribute | |
| fs_locations, but where the bit mask includes attributes that are not | | fs_locations, but where the bitmask includes attributes that are not | |
| supported, GETATTR will not return an error, but will return the mask | | supported, GETATTR will not return an error but will return the mask | |
| of the actual attributes supported with the results. | | of the actual attributes supported with the results. | |
| | | | |
| Handling of VERIFY/NVERIFY is similar to GETATTR in that if the | | Handling of VERIFY/NVERIFY is similar to GETATTR in that if the | |
| attribute mask does not include fs_locations the error NFS4ERR_MOVED | | attribute mask does not include fs_locations the error NFS4ERR_MOVED | |
| will result. It differs in that any appearance in the attribute mask | | will result. It differs in that any appearance in the attribute mask | |
| of an attribute not supported for an absent file system (and note | | of an attribute not supported for an absent file system (and note | |
| that this will include some normally REQUIRED attributes) will also | | that this will include some normally REQUIRED attributes) will also | |
| cause an NFS4ERR_MOVED result. | | cause an NFS4ERR_MOVED result. | |
| | | | |
| 8.3.2. READDIR and Absent File Systems | | 8.3.2. READDIR and Absent File Systems | |
| | | | |
| A READDIR performed when the current filehandle is within an absent | | A READDIR performed when the current filehandle is within an absent | |
| file system will result in an NFS4ERR_MOVED error, since, unlike the | | file system will result in an NFS4ERR_MOVED error, since, unlike the | |
| case of GETATTR, no such exception is made for READDIR. | | case of GETATTR, no such exception is made for READDIR. | |
| | | | |
| Attributes for an absent file system may be fetched via a READDIR for | | Attributes for an absent file system may be fetched via a READDIR for | |
| a directory in a present file system, when that directory contains | | a directory in a present file system, when that directory contains | |
| the root directories of one or more absent file systems. In this | | the root directories of one or more absent file systems. In this | |
| case, the handling is as follows: | | case, the handling is as follows: | |
| | | | |
|
| o If the attribute set requested includes fs_locations, then | | o If the attribute set requested includes fs_locations, then the | |
| fetching of attributes proceeds normally and no NFS4ERR_MOVED | | fetching of attributes proceeds normally, and no NFS4ERR_MOVED | |
| indication is returned, even when the rdattr_error attribute is | | indication is returned even when the rdattr_error attribute is | |
| requested. | | requested. | |
| | | | |
| o If the attribute set requested does not include fs_locations, then | | o If the attribute set requested does not include fs_locations, then | |
| if the rdattr_error attribute is requested, each directory entry | | if the rdattr_error attribute is requested, each directory entry | |
| for the root of an absent file system will report NFS4ERR_MOVED as | | for the root of an absent file system will report NFS4ERR_MOVED as | |
| the value of the rdattr_error attribute. | | the value of the rdattr_error attribute. | |
| | | | |
| o If the attribute set requested does not include either of the | | o If the attribute set requested does not include either of the | |
|
| attributes fs_locations or rdattr_error then the occurrence of the | | attributes fs_locations or rdattr_error, then the occurrence of | |
| root of an absent file system within the directory will result in | | the root of an absent file system within the directory will result | |
| the READDIR failing with an NFS4ERR_MOVED error. | | in the READDIR failing with an NFS4ERR_MOVED error. | |
| | | | |
| o The unavailability of an attribute because of a file system's | | o The unavailability of an attribute because of a file system's | |
| absence, even one that is ordinarily REQUIRED, does not result in | | absence, even one that is ordinarily REQUIRED, does not result in | |
| any error indication. The set of attributes returned for the root | | any error indication. The set of attributes returned for the root | |
| directory of the absent file system in that case is simply | | directory of the absent file system in that case is simply | |
| restricted to those actually available. | | restricted to those actually available. | |
| | | | |
| 8.4. Uses of Location Information | | 8.4. Uses of Location Information | |
| | | | |
| The location-bearing attribute of fs_locations provides, together | | The location-bearing attribute of fs_locations provides, together | |
| | | | |
| skipping to change at page 81, line 51 | | skipping to change at page 85, line 12 | |
| facilities in providing reliable, manageable, and scalable data | | facilities in providing reliable, manageable, and scalable data | |
| access. | | access. | |
| | | | |
| When a file system is present, these attributes can provide | | When a file system is present, these attributes can provide | |
| alternative locations, to be used to access the same data, in the | | alternative locations, to be used to access the same data, in the | |
| event of server failures, communications problems, or other | | event of server failures, communications problems, or other | |
| difficulties that make continued access to the current file system | | difficulties that make continued access to the current file system | |
| impossible or otherwise impractical. Under some circumstances, | | impossible or otherwise impractical. Under some circumstances, | |
| multiple alternative locations may be used simultaneously to provide | | multiple alternative locations may be used simultaneously to provide | |
| higher-performance access to the file system in question. Provision | | higher-performance access to the file system in question. Provision | |
|
| of such alternative locations is referred to as "replication" | | of such alternative locations is referred to as "replication", | |
| although there are cases in which replicated sets of data are not in | | although there are cases in which replicated sets of data are not in | |
|
| fact present, and the replicas are instead different paths to the | | fact present and the replicas are instead different paths to the same | |
| same data. | | data. | |
| | | | |
| When a file system is present and subsequently becomes absent, | | When a file system is present and subsequently becomes absent, | |
| clients can be given the opportunity to have continued access to | | clients can be given the opportunity to have continued access to | |
| their data, at an alternative location. Transfer of the file system | | their data, at an alternative location. Transfer of the file system | |
| contents to the new location is referred to as "migration". See | | contents to the new location is referred to as "migration". See | |
| Section 8.4.2 for details. | | Section 8.4.2 for details. | |
| | | | |
|
| Alternative locations may be be physical replicas of the file system | | Alternative locations may be physical replicas of the file system | |
| data or alternative communication paths to the same server or, in the | | data or alternative communication paths to the same server or, in the | |
| case of various forms of server clustering, another server providing | | case of various forms of server clustering, another server providing | |
| access to the same physical file system. The client's | | access to the same physical file system. The client's | |
| responsibilities in dealing with this transition depend on the | | responsibilities in dealing with this transition depend on the | |
| specific nature of the new access path as well as how and whether | | specific nature of the new access path as well as how and whether | |
| data was in fact migrated. These issues will be discussed in detail | | data was in fact migrated. These issues will be discussed in detail | |
| below. | | below. | |
| | | | |
| Where a file system was not previously present, specification of file | | Where a file system was not previously present, specification of file | |
| system location provides a means by which file systems located on one | | system location provides a means by which file systems located on one | |
| | | | |
| skipping to change at page 82, line 36 | | skipping to change at page 85, line 46 | |
| designation of such a location, in place of an absent file system, is | | designation of such a location, in place of an absent file system, is | |
| called a "referral". | | called a "referral". | |
| | | | |
| Because client support for location-related attributes is OPTIONAL, a | | Because client support for location-related attributes is OPTIONAL, a | |
| server may (but is not required to) take action to hide migration and | | server may (but is not required to) take action to hide migration and | |
| referral events from such clients, by acting as a proxy, for example. | | referral events from such clients, by acting as a proxy, for example. | |
| | | | |
| 8.4.1. File System Replication | | 8.4.1. File System Replication | |
| | | | |
| The fs_locations attribute provides alternative locations, to be used | | The fs_locations attribute provides alternative locations, to be used | |
|
| to access data in place of or in addition to the current file system | | to access data in place of, or in addition to, the current file | |
| instance. On first access to a file system, the client should obtain | | system instance. On first access to a file system, the client should | |
| the value of the set of alternative locations by interrogating the | | obtain the value of the set of alternative locations by interrogating | |
| fs_locations attribute. | | the fs_locations attribute. | |
| | | | |
| In the event that server failures, communications problems, or other | | In the event that server failures, communications problems, or other | |
| difficulties make continued access to the current file system | | difficulties make continued access to the current file system | |
| impossible or otherwise impractical, the client can use the | | impossible or otherwise impractical, the client can use the | |
| alternative locations as a way to get continued access to its data. | | alternative locations as a way to get continued access to its data. | |
| Multiple locations may be used simultaneously, to provide higher | | Multiple locations may be used simultaneously, to provide higher | |
| performance through the exploitation of multiple paths between client | | performance through the exploitation of multiple paths between client | |
| and target file system. | | and target file system. | |
| | | | |
| Multiple server addresses, whether they are derived from a single | | Multiple server addresses, whether they are derived from a single | |
| | | | |
| skipping to change at page 83, line 20 | | skipping to change at page 86, line 31 | |
| given the opportunity to have continued access to their data, at an | | given the opportunity to have continued access to their data, at an | |
| alternative location, as specified by the fs_locations attribute. | | alternative location, as specified by the fs_locations attribute. | |
| Typically, a client will be accessing the file system in question, | | Typically, a client will be accessing the file system in question, | |
| get an NFS4ERR_MOVED error, and then use the fs_locations attribute | | get an NFS4ERR_MOVED error, and then use the fs_locations attribute | |
| to determine the new location of the data. | | to determine the new location of the data. | |
| | | | |
| Such migration can be helpful in providing load balancing or general | | Such migration can be helpful in providing load balancing or general | |
| resource reallocation. The protocol does not specify how the file | | resource reallocation. The protocol does not specify how the file | |
| system will be moved between servers. It is anticipated that a | | system will be moved between servers. It is anticipated that a | |
| number of different server-to-server transfer mechanisms might be | | number of different server-to-server transfer mechanisms might be | |
|
| used with the choice left to the server implementer. The NFSv4 | | used, with the choice left to the server implementer. The NFSv4 | |
| protocol specifies the method used to communicate the migration event | | protocol specifies the method used to communicate the migration event | |
| between client and server. | | between client and server. | |
| | | | |
| When an alternative location is designated as the target for | | When an alternative location is designated as the target for | |
| migration, it must designate the same data. Where file systems are | | migration, it must designate the same data. Where file systems are | |
| writable, a change made on the original file system must be visible | | writable, a change made on the original file system must be visible | |
| on all migration targets. Where a file system is not writable but | | on all migration targets. Where a file system is not writable but | |
| represents a read-only copy (possibly periodically updated) of a | | represents a read-only copy (possibly periodically updated) of a | |
| writable file system, similar requirements apply to the propagation | | writable file system, similar requirements apply to the propagation | |
| of updates. Any change visible in the original file system must | | of updates. Any change visible in the original file system must | |
| | | | |
| skipping to change at page 84, line 5 | | skipping to change at page 87, line 15 | |
| establishment of site-wide or organization-wide namespaces, or even | | establishment of site-wide or organization-wide namespaces, or even | |
| knitting such together into a truly global namespace. | | knitting such together into a truly global namespace. | |
| | | | |
| Referrals occur when a client determines, upon first referencing a | | Referrals occur when a client determines, upon first referencing a | |
| position in the current namespace, that it is part of a new file | | position in the current namespace, that it is part of a new file | |
| system and that the file system is absent. When this occurs, | | system and that the file system is absent. When this occurs, | |
| typically by receiving the error NFS4ERR_MOVED, the actual location | | typically by receiving the error NFS4ERR_MOVED, the actual location | |
| or locations of the file system can be determined by fetching the | | or locations of the file system can be determined by fetching the | |
| fs_locations attribute. | | fs_locations attribute. | |
| | | | |
|
| The locations-related attribute may designate a single file system | | The location-related attribute may designate a single file system | |
| location or multiple file system locations, to be selected based on | | location or multiple file system locations, to be selected based on | |
| the needs of the client. | | the needs of the client. | |
| | | | |
| Use of multi-server namespaces is enabled by NFSv4 but is not | | Use of multi-server namespaces is enabled by NFSv4 but is not | |
| required. The use of multi-server namespaces and their scope will | | required. The use of multi-server namespaces and their scope will | |
| depend on the applications used and system administration | | depend on the applications used and system administration | |
| preferences. | | preferences. | |
| | | | |
| Multi-server namespaces can be established by a single server | | Multi-server namespaces can be established by a single server | |
| providing a large set of referrals to all of the included file | | providing a large set of referrals to all of the included file | |
| | | | |
| skipping to change at page 84, line 48 | | skipping to change at page 88, line 11 | |
| corresponding file system locations can be used as alternative | | corresponding file system locations can be used as alternative | |
| locations, just as those explicitly specified via the fs_locations | | locations, just as those explicitly specified via the fs_locations | |
| attribute. | | attribute. | |
| | | | |
| If a single location entry designates multiple server IP addresses, | | If a single location entry designates multiple server IP addresses, | |
| the client should choose a single one to use. When two server | | the client should choose a single one to use. When two server | |
| addresses are designated by a single location entry and they | | addresses are designated by a single location entry and they | |
| correspond to different servers, this normally indicates some sort of | | correspond to different servers, this normally indicates some sort of | |
| misconfiguration, and so the client should avoid using such location | | misconfiguration, and so the client should avoid using such location | |
| entries when alternatives are available. When they are not, clients | | entries when alternatives are available. When they are not, clients | |
|
| should pick one of IP addresses and use it, without using others that | | should pick one of the IP addresses and use it, without using others | |
| are not directed to the same server. | | that are not directed to the same server. | |
| | | | |
| 8.6. Additional Client-Side Considerations | | 8.6. Additional Client-Side Considerations | |
| | | | |
| When clients make use of servers that implement referrals, | | When clients make use of servers that implement referrals, | |
| replication, and migration, care should be taken that a user who | | replication, and migration, care should be taken that a user who | |
| mounts a given file system that includes a referral or a relocated | | mounts a given file system that includes a referral or a relocated | |
| file system continues to see a coherent picture of that user-side | | file system continues to see a coherent picture of that user-side | |
| file system despite the fact that it contains a number of server-side | | file system despite the fact that it contains a number of server-side | |
| file systems that may be on different servers. | | file systems that may be on different servers. | |
| | | | |
|
| One important issue is upward navigation from the root of a server- | | One important issue is upward navigation from the root of a | |
| side file system to its parent (specified as ".." in UNIX), in the | | server-side file system to its parent (specified as ".." in UNIX), in | |
| case in which it transitions to that file system as a result of | | the case in which it transitions to that file system as a result of | |
| referral, migration, or a transition as a result of replication. | | referral, migration, or a transition as a result of replication. | |
| When the client is at such a point, and it needs to ascend to the | | When the client is at such a point, and it needs to ascend to the | |
| parent, it must go back to the parent as seen within the multi-server | | parent, it must go back to the parent as seen within the multi-server | |
| namespace rather than sending a LOOKUPP operation to the server, | | namespace rather than sending a LOOKUPP operation to the server, | |
| which would result in the parent within that server's single-server | | which would result in the parent within that server's single-server | |
| namespace. In order to do this, the client needs to remember the | | namespace. In order to do this, the client needs to remember the | |
| filehandles that represent such file system roots and use these | | filehandles that represent such file system roots and use these | |
| instead of issuing a LOOKUPP operation to the current server. This | | instead of issuing a LOOKUPP operation to the current server. This | |
| will allow the client to present to applications a consistent | | will allow the client to present to applications a consistent | |
| namespace, where upward navigation and downward navigation are | | namespace, where upward navigation and downward navigation are | |
| consistent. | | consistent. | |
| | | | |
| Another issue concerns refresh of referral locations. When referrals | | Another issue concerns refresh of referral locations. When referrals | |
| are used extensively, they may change as server configurations | | are used extensively, they may change as server configurations | |
| change. It is expected that clients will cache information related | | change. It is expected that clients will cache information related | |
| to traversing referrals so that future client-side requests are | | to traversing referrals so that future client-side requests are | |
| resolved locally without server communication. This is usually | | resolved locally without server communication. This is usually | |
|
| rooted in client-side name look up caching. Clients should | | rooted in client-side name lookup caching. Clients should | |
| periodically purge this data for referral points in order to detect | | periodically purge this data for referral points in order to detect | |
| changes in location information. | | changes in location information. | |
| | | | |
| A potential problem exists if a client were to allow an open-owner to | | A potential problem exists if a client were to allow an open-owner to | |
|
| have state on multiple file systems on server, in that it is unclear | | have state on multiple file systems on a server, in that it is | |
| how the sequence numbers associated with open-owners are to be dealt | | unclear how the sequence numbers associated with open-owners are to | |
| with, in the event of transparent state migration. A client can | | be dealt with, in the event of transparent state migration. A client | |
| avoid such a situation, if it ensures that any use of an open-owner | | can avoid such a situation if it ensures that any use of an | |
| is confined to a single file system. | | open-owner is confined to a single file system. | |
| | | | |
| A server MAY decline to migrate state associated with open-owners | | A server MAY decline to migrate state associated with open-owners | |
| that span multiple file systems. In cases in which the server | | that span multiple file systems. In cases in which the server | |
| chooses not to migrate such state, the server MUST return | | chooses not to migrate such state, the server MUST return | |
| NFS4ERR_BAD_STATEID when the client uses those stateids on the new | | NFS4ERR_BAD_STATEID when the client uses those stateids on the new | |
| server. | | server. | |
| | | | |
| The server MUST return NFS4ERR_STALE_STATEID when the client uses | | The server MUST return NFS4ERR_STALE_STATEID when the client uses | |
| those stateids on the old server, regardless of whether migration has | | those stateids on the old server, regardless of whether migration has | |
| occurred or not. | | occurred or not. | |
| | | | |
| 8.7. Effecting File System Referrals | | 8.7. Effecting File System Referrals | |
| | | | |
|
| Referrals are effected when an absent file system is encountered, and | | Referrals are effected when an absent file system is encountered and | |
| one or more alternative locations are made available by the | | one or more alternative locations are made available by the | |
| fs_locations attribute. The client will typically get an | | fs_locations attribute. The client will typically get an | |
| NFS4ERR_MOVED error, fetch the appropriate location information, and | | NFS4ERR_MOVED error, fetch the appropriate location information, and | |
| proceed to access the file system on a different server, even though | | proceed to access the file system on a different server, even though | |
| it retains its logical position within the original namespace. | | it retains its logical position within the original namespace. | |
| Referrals differ from migration events in that they happen only when | | Referrals differ from migration events in that they happen only when | |
| the client has not previously referenced the file system in question | | the client has not previously referenced the file system in question | |
| (so there is nothing to transition). Referrals can only come into | | (so there is nothing to transition). Referrals can only come into | |
| effect when an absent file system is encountered at its root. | | effect when an absent file system is encountered at its root. | |
| | | | |
| The examples given in the sections below are somewhat artificial in | | The examples given in the sections below are somewhat artificial in | |
|
| that an actual client will not typically do a multi-component look | | that an actual client will not typically do a multi-component lookup | |
| up, but will have cached information regarding the upper levels of | | but will have cached information regarding the upper levels of the | |
| the name hierarchy. However, these example are chosen to make the | | name hierarchy. However, these example are chosen to make the | |
| required behavior clear and easy to put within the scope of a small | | required behavior clear and easy to put within the scope of a small | |
| number of requests, without getting unduly into details of how | | number of requests, without getting unduly into details of how | |
| specific clients might choose to cache things. | | specific clients might choose to cache things. | |
| | | | |
| 8.7.1. Referral Example (LOOKUP) | | 8.7.1. Referral Example (LOOKUP) | |
| | | | |
| Let us suppose that the following COMPOUND is sent in an environment | | Let us suppose that the following COMPOUND is sent in an environment | |
| in which /this/is/the/path is absent from the target server. This | | in which /this/is/the/path is absent from the target server. This | |
| may be for a number of reasons. It may be the case that the file | | may be for a number of reasons. It may be the case that the file | |
| system has moved, or it may be the case that the target server is | | system has moved, or it may be the case that the target server is | |
| | | | |
| skipping to change at page 86, line 51 | | skipping to change at page 90, line 17 | |
| o LOOKUP "this" | | o LOOKUP "this" | |
| | | | |
| o LOOKUP "is" | | o LOOKUP "is" | |
| | | | |
| o LOOKUP "the" | | o LOOKUP "the" | |
| | | | |
| o LOOKUP "path" | | o LOOKUP "path" | |
| | | | |
| o GETFH | | o GETFH | |
| | | | |
|
| o GETATTR(fsid,fileid,size,time_modify) | | o GETATTR(fsid, fileid, size, time_modify) | |
| Under the given circumstances, the following will be the result. | | | |
| | | Under the given circumstances, the following will be the result: | |
| | | | |
| o PUTROOTFH --> NFS_OK. The current fh is now the root of the | | o PUTROOTFH --> NFS_OK. The current fh is now the root of the | |
| pseudo-fs. | | pseudo-fs. | |
| | | | |
| o LOOKUP "this" --> NFS_OK. The current fh is for /this and is | | o LOOKUP "this" --> NFS_OK. The current fh is for /this and is | |
| within the pseudo-fs. | | within the pseudo-fs. | |
| | | | |
| o LOOKUP "is" --> NFS_OK. The current fh is for /this/is and is | | o LOOKUP "is" --> NFS_OK. The current fh is for /this/is and is | |
| within the pseudo-fs. | | within the pseudo-fs. | |
| | | | |
| o LOOKUP "the" --> NFS_OK. The current fh is for /this/is/the and | | o LOOKUP "the" --> NFS_OK. The current fh is for /this/is/the and | |
| is within the pseudo-fs. | | is within the pseudo-fs. | |
| | | | |
| o LOOKUP "path" --> NFS_OK. The current fh is for /this/is/the/path | | o LOOKUP "path" --> NFS_OK. The current fh is for /this/is/the/path | |
|
| and is within a new, absent file system, but ... the client will | | and is within a new, absent file system, but ... the client will | |
| never see the value of that fh. | | never see the value of that fh. | |
| | | | |
|
| o GETFH --> NFS4ERR_MOVED. Fails because current fh is in an absent | | o GETFH --> NFS4ERR_MOVED. Fails, because the current fh is in an | |
| file system at the start of the operation, and the specification | | absent file system at the start of the operation and the | |
| makes no exception for GETFH. | | specification makes no exception for GETFH. | |
| | | | |
|
| o GETATTR(fsid,fileid,size,time_modify) Not executed because the | | o GETATTR(fsid, fileid, size, time_modify). Not executed, because | |
| failure of the GETFH stops processing of the COMPOUND. | | the failure of the GETFH stops the processing of the COMPOUND. | |
| | | | |
| Given the failure of the GETFH, the client has the job of determining | | Given the failure of the GETFH, the client has the job of determining | |
| the root of the absent file system and where to find that file | | the root of the absent file system and where to find that file | |
| system, i.e., the server and path relative to that server's root fh. | | system, i.e., the server and path relative to that server's root fh. | |
| Note here that in this example, the client did not obtain filehandles | | Note here that in this example, the client did not obtain filehandles | |
| and attribute information (e.g., fsid) for the intermediate | | and attribute information (e.g., fsid) for the intermediate | |
| directories, so that it would not be sure where the absent file | | directories, so that it would not be sure where the absent file | |
| system starts. It could be the case, for example, that /this/is/the | | system starts. It could be the case, for example, that /this/is/the | |
| is the root of the moved file system and that the reason that the | | is the root of the moved file system and that the reason that the | |
|
| look up of "path" succeeded is that the file system was not absent on | | lookup of "path" succeeded is that the file system was not absent on | |
| that operation but was moved between the last LOOKUP and the GETFH | | that operation but was moved between the last LOOKUP and the GETFH | |
| (since COMPOUND is not atomic). Even if we had the fsids for all of | | (since COMPOUND is not atomic). Even if we had the fsids for all of | |
|
| the intermediate directories, we could have no way of knowing that / | | the intermediate directories, we could have no way of knowing that | |
| this/is/the/path was the root of a new file system, since we don't | | /this/is/the/path was the root of a new file system, since we don't | |
| yet have its fsid. | | yet have its fsid. | |
| | | | |
| In order to get the necessary information, let us re-send the chain | | In order to get the necessary information, let us re-send the chain | |
| of LOOKUPs with GETFHs and GETATTRs to at least get the fsids so we | | of LOOKUPs with GETFHs and GETATTRs to at least get the fsids so we | |
| can be sure where the appropriate file system boundaries are. The | | can be sure where the appropriate file system boundaries are. The | |
|
| client could choose to get fs_locations at the same time but in most | | client could choose to get fs_locations at the same time, but in most | |
| cases the client will have a good guess as to where file system | | cases the client will have a good guess as to where the file system | |
| boundaries are (because of where NFS4ERR_MOVED was, and was not, | | boundaries are (because of where NFS4ERR_MOVED was, and was not, | |
|
| received) making fetching of fs_locations unnecessary. | | received), making the fetching of fs_locations unnecessary. | |
| | | | |
| OP01: PUTROOTFH --> NFS_OK | | OP01: PUTROOTFH --> NFS_OK | |
| | | | |
|
| - Current fh is root of pseudo-fs. | | - The current fh is at the root of the pseudo-fs. | |
| | | | |
| OP02: GETATTR(fsid) --> NFS_OK | | OP02: GETATTR(fsid) --> NFS_OK | |
| | | | |
| - Just for completeness. Normally, clients will know the fsid of | | - Just for completeness. Normally, clients will know the fsid of | |
| the pseudo-fs as soon as they establish communication with a | | the pseudo-fs as soon as they establish communication with a | |
| server. | | server. | |
| | | | |
| OP03: LOOKUP "this" --> NFS_OK | | OP03: LOOKUP "this" --> NFS_OK | |
| | | | |
| OP04: GETATTR(fsid) --> NFS_OK | | OP04: GETATTR(fsid) --> NFS_OK | |
| | | | |
|
| - Get current fsid to see where file system boundaries are. The | | - Get the current fsid to see where the file system boundaries are. | |
| fsid will be that for the pseudo-fs in this example, so no | | The fsid will be that for the pseudo-fs in this example, so no | |
| boundary. | | boundary. | |
| | | | |
| OP05: GETFH --> NFS_OK | | OP05: GETFH --> NFS_OK | |
| | | | |
|
| - Current fh is for /this and is within pseudo-fs. | | - The current fh is for /this and is within the pseudo-fs. | |
| | | | |
| OP06: LOOKUP "is" --> NFS_OK | | OP06: LOOKUP "is" --> NFS_OK | |
| | | | |
|
| - Current fh is for /this/is and is within pseudo-fs. | | - The current fh is for /this/is and is within the pseudo-fs. | |
| | | | |
| OP07: GETATTR(fsid) --> NFS_OK | | OP07: GETATTR(fsid) --> NFS_OK | |
| | | | |
|
| - Get current fsid to see where file system boundaries are. The | | - Get the current fsid to see where the file system boundaries are. | |
| fsid will be that for the pseudo-fs in this example, so no | | The fsid will be that for the pseudo-fs in this example, so no | |
| boundary. | | boundary. | |
| | | | |
| OP08: GETFH --> NFS_OK | | OP08: GETFH --> NFS_OK | |
| | | | |
|
| - Current fh is for /this/is and is within pseudo-fs. | | - The current fh is for /this/is and is within the pseudo-fs. | |
| | | | |
| OP09: LOOKUP "the" --> NFS_OK | | OP09: LOOKUP "the" --> NFS_OK | |
| | | | |
|
| - Current fh is for /this/is/the and is within pseudo-fs. | | - The current fh is for /this/is/the and is within the pseudo-fs. | |
| | | | |
| OP10: GETATTR(fsid) --> NFS_OK | | OP10: GETATTR(fsid) --> NFS_OK | |
| | | | |
|
| - Get current fsid to see where file system boundaries are. The | | - Get the current fsid to see where the file system boundaries are. | |
| fsid will be that for the pseudo-fs in this example, so no | | The fsid will be that for the pseudo-fs in this example, so no | |
| boundary. | | boundary. | |
| | | | |
| OP11: GETFH --> NFS_OK | | OP11: GETFH --> NFS_OK | |
|
| - Current fh is for /this/is/the and is within pseudo-fs. | | | |
| | | - The current fh is for /this/is/the and is within the pseudo-fs. | |
| | | | |
| OP12: LOOKUP "path" --> NFS_OK | | OP12: LOOKUP "path" --> NFS_OK | |
| | | | |
|
| - Current fh is for /this/is/the/path and is within a new, absent | | - The current fh is for /this/is/the/path and is within a new, | |
| file system, but ... | | absent file system, but ... | |
| | | | |
| - The client will never see the value of that fh. | | - The client will never see the value of that fh. | |
| | | | |
| OP13: GETATTR(fsid, fs_locations) --> NFS_OK | | OP13: GETATTR(fsid, fs_locations) --> NFS_OK | |
| | | | |
| - We are getting the fsid to know where the file system boundaries | | - We are getting the fsid to know where the file system boundaries | |
| are. In this operation, the fsid will be different than that of | | are. In this operation, the fsid will be different than that of | |
| the parent directory (which in turn was retrieved in OP10). Note | | the parent directory (which in turn was retrieved in OP10). Note | |
| that the fsid we are given will not necessarily be preserved at | | that the fsid we are given will not necessarily be preserved at | |
| the new location. That fsid might be different, and in fact the | | the new location. That fsid might be different, and in fact the | |
| fsid we have for this file system might be a valid fsid of a | | fsid we have for this file system might be a valid fsid of a | |
| different file system on that new server. | | different file system on that new server. | |
| | | | |
| - In this particular case, we are pretty sure anyway that what has | | - In this particular case, we are pretty sure anyway that what has | |
| moved is /this/is/the/path rather than /this/is/the since we have | | moved is /this/is/the/path rather than /this/is/the since we have | |
| the fsid of the latter and it is that of the pseudo-fs, which | | the fsid of the latter and it is that of the pseudo-fs, which | |
| presumably cannot move. However, in other examples, we might not | | presumably cannot move. However, in other examples, we might not | |
| have this kind of information to rely on (e.g., /this/is/the might | | have this kind of information to rely on (e.g., /this/is/the might | |
|
| be a non-pseudo file system separate from /this/is/the/path), so | | be a non-pseudo-file system separate from /this/is/the/path), so | |
| we need to have other reliable source information on the boundary | | we need to have other reliable source information on the boundary | |
| of the file system that is moved. If, for example, the file | | of the file system that is moved. If, for example, the file | |
| system /this/is had moved, we would have a case of migration | | system /this/is had moved, we would have a case of migration | |
| rather than referral, and once the boundaries of the migrated file | | rather than referral, and once the boundaries of the migrated file | |
|
| system was clear we could fetch fs_locations. | | system were clear we could fetch fs_locations. | |
| | | | |
| - We are fetching fs_locations because the fact that we got an | | - We are fetching fs_locations because the fact that we got an | |
|
| NFS4ERR_MOVED at this point means that it is most likely that this | | NFS4ERR_MOVED at this point means that this is most likely a | |
| is a referral and we need the destination. Even if it is the case | | referral and we need the destination. Even if it is the case that | |
| that /this/is/the is a file system that has migrated, we will | | /this/is/the is a file system that has migrated, we will still | |
| still need the location information for that file system. | | need the location information for that file system. | |
| | | | |
| OP14: GETFH --> NFS4ERR_MOVED | | OP14: GETFH --> NFS4ERR_MOVED | |
| | | | |
| - Fails because current fh is in an absent file system at the start | | - Fails because current fh is in an absent file system at the start | |
| of the operation, and the specification makes no exception for | | of the operation, and the specification makes no exception for | |
| GETFH. Note that this means the server will never send the client | | GETFH. Note that this means the server will never send the client | |
| a filehandle from within an absent file system. | | a filehandle from within an absent file system. | |
| | | | |
| Given the above, the client knows where the root of the absent file | | Given the above, the client knows where the root of the absent file | |
| system is (/this/is/the/path) by noting where the change of fsid | | system is (/this/is/the/path) by noting where the change of fsid | |
| occurred (between "the" and "path"). The fs_locations attribute also | | occurred (between "the" and "path"). The fs_locations attribute also | |
|
| gives the client the actual location of the absent file system, so | | gives the client the actual location of the absent file system so | |
| that the referral can proceed. The server gives the client the bare | | that the referral can proceed. The server gives the client the bare | |
| minimum of information about the absent file system so that there | | minimum of information about the absent file system so that there | |
| will be very little scope for problems of conflict between | | will be very little scope for problems of conflict between | |
| information sent by the referring server and information of the file | | information sent by the referring server and information of the file | |
| system's home. No filehandles and very few attributes are present on | | system's home. No filehandles and very few attributes are present on | |
| the referring server, and the client can treat those it receives as | | the referring server, and the client can treat those it receives as | |
| transient information with the function of enabling the referral. | | transient information with the function of enabling the referral. | |
| | | | |
| 8.7.2. Referral Example (READDIR) | | 8.7.2. Referral Example (READDIR) | |
| | | | |
| Another context in which a client may encounter referrals is when it | | Another context in which a client may encounter referrals is when it | |
|
| does a READDIR on a directory in which some of the sub-directories | | does a READDIR on a directory in which some of the subdirectories are | |
| are the roots of absent file systems. | | the roots of absent file systems. | |
| | | | |
| Suppose such a directory is read as follows: | | Suppose such a directory is read as follows: | |
| | | | |
| o PUTROOTFH | | o PUTROOTFH | |
| | | | |
| o LOOKUP "this" | | o LOOKUP "this" | |
| | | | |
| o LOOKUP "is" | | o LOOKUP "is" | |
| | | | |
| o LOOKUP "the" | | o LOOKUP "the" | |
| | | | |
|
| o READDIR (fsid, size, time_modify, mounted_on_fileid) | | o READDIR(fsid, size, time_modify, mounted_on_fileid) | |
| | | | |
| In this case, because rdattr_error is not requested, fs_locations is | | In this case, because rdattr_error is not requested, fs_locations is | |
| not requested, and some of the attributes cannot be provided, the | | not requested, and some of the attributes cannot be provided, the | |
| result will be an NFS4ERR_MOVED error on the READDIR, with the | | result will be an NFS4ERR_MOVED error on the READDIR, with the | |
| detailed results as follows: | | detailed results as follows: | |
| | | | |
| o PUTROOTFH --> NFS_OK. The current fh is at the root of the | | o PUTROOTFH --> NFS_OK. The current fh is at the root of the | |
| pseudo-fs. | | pseudo-fs. | |
| | | | |
| o LOOKUP "this" --> NFS_OK. The current fh is for /this and is | | o LOOKUP "this" --> NFS_OK. The current fh is for /this and is | |
| within the pseudo-fs. | | within the pseudo-fs. | |
| | | | |
| o LOOKUP "is" --> NFS_OK. The current fh is for /this/is and is | | o LOOKUP "is" --> NFS_OK. The current fh is for /this/is and is | |
| within the pseudo-fs. | | within the pseudo-fs. | |
| | | | |
| o LOOKUP "the" --> NFS_OK. The current fh is for /this/is/the and | | o LOOKUP "the" --> NFS_OK. The current fh is for /this/is/the and | |
| is within the pseudo-fs. | | is within the pseudo-fs. | |
| | | | |
|
| o READDIR (fsid, size, time_modify, mounted_on_fileid) --> | | o READDIR(fsid, size, time_modify, mounted_on_fileid) --> | |
| NFS4ERR_MOVED. Note that the same error would have been returned | | NFS4ERR_MOVED. Note that the same error would have been returned | |
| if /this/is/the had migrated, but it is returned because the | | if /this/is/the had migrated, but it is returned because the | |
| directory contains the root of an absent file system. | | directory contains the root of an absent file system. | |
| | | | |
| So now suppose that we re-send with rdattr_error: | | So now suppose that we re-send with rdattr_error: | |
| | | | |
| o PUTROOTFH | | o PUTROOTFH | |
| | | | |
| o LOOKUP "this" | | o LOOKUP "this" | |
| | | | |
| o LOOKUP "is" | | o LOOKUP "is" | |
| | | | |
| o LOOKUP "the" | | o LOOKUP "the" | |
| | | | |
|
| o READDIR (rdattr_error, fsid, size, time_modify, mounted_on_fileid) | | o READDIR(rdattr_error, fsid, size, time_modify, mounted_on_fileid) | |
| | | | |
| The results will be: | | The results will be: | |
| | | | |
| o PUTROOTFH --> NFS_OK. The current fh is at the root of the | | o PUTROOTFH --> NFS_OK. The current fh is at the root of the | |
| pseudo-fs. | | pseudo-fs. | |
| | | | |
| o LOOKUP "this" --> NFS_OK. The current fh is for /this and is | | o LOOKUP "this" --> NFS_OK. The current fh is for /this and is | |
| within the pseudo-fs. | | within the pseudo-fs. | |
| | | | |
| o LOOKUP "is" --> NFS_OK. The current fh is for /this/is and is | | o LOOKUP "is" --> NFS_OK. The current fh is for /this/is and is | |
| within the pseudo-fs. | | within the pseudo-fs. | |
| | | | |
| o LOOKUP "the" --> NFS_OK. The current fh is for /this/is/the and | | o LOOKUP "the" --> NFS_OK. The current fh is for /this/is/the and | |
| is within the pseudo-fs. | | is within the pseudo-fs. | |
| | | | |
|
| o READDIR (rdattr_error, fsid, size, time_modify, mounted_on_fileid) | | o READDIR(rdattr_error, fsid, size, time_modify, mounted_on_fileid) | |
| --> NFS_OK. The attributes for directory entry with the component | | --> NFS_OK. The attributes for the directory entry with the | |
| named "path" will only contain rdattr_error with the value | | component named "path" will only contain rdattr_error with the | |
| NFS4ERR_MOVED, together with an fsid value and a value for | | value NFS4ERR_MOVED, together with an fsid value and a value for | |
| mounted_on_fileid. | | mounted_on_fileid. | |
| | | | |
| So suppose we do another READDIR to get fs_locations (although we | | So suppose we do another READDIR to get fs_locations (although we | |
|
| could have used a GETATTR directly, as in Section 8.7.1). | | could have used a GETATTR directly, as in Section 8.7.1): | |
| | | | |
| o PUTROOTFH | | o PUTROOTFH | |
| | | | |
| o LOOKUP "this" | | o LOOKUP "this" | |
| | | | |
| o LOOKUP "is" | | o LOOKUP "is" | |
| | | | |
| o LOOKUP "the" | | o LOOKUP "the" | |
| | | | |
|
| o READDIR (rdattr_error, fs_locations, mounted_on_fileid, fsid, | | o READDIR(rdattr_error, fs_locations, mounted_on_fileid, fsid, size, | |
| size, time_modify) | | time_modify) | |
| | | | |
| The results would be: | | The results would be: | |
| | | | |
| o PUTROOTFH --> NFS_OK. The current fh is at the root of the | | o PUTROOTFH --> NFS_OK. The current fh is at the root of the | |
| pseudo-fs. | | pseudo-fs. | |
| | | | |
| o LOOKUP "this" --> NFS_OK. The current fh is for /this and is | | o LOOKUP "this" --> NFS_OK. The current fh is for /this and is | |
| within the pseudo-fs. | | within the pseudo-fs. | |
| | | | |
| o LOOKUP "is" --> NFS_OK. The current fh is for /this/is and is | | o LOOKUP "is" --> NFS_OK. The current fh is for /this/is and is | |
| within the pseudo-fs. | | within the pseudo-fs. | |
| | | | |
| o LOOKUP "the" --> NFS_OK. The current fh is for /this/is/the and | | o LOOKUP "the" --> NFS_OK. The current fh is for /this/is/the and | |
| is within the pseudo-fs. | | is within the pseudo-fs. | |
| | | | |
|
| o READDIR (rdattr_error, fs_locations, mounted_on_fileid, fsid, | | o READDIR(rdattr_error, fs_locations, mounted_on_fileid, fsid, size, | |
| size, time_modify) --> NFS_OK. The attributes will be as shown | | time_modify) --> NFS_OK. The attributes will be as shown below. | |
| below. | | | |
| | | | |
| The attributes for the directory entry with the component named | | The attributes for the directory entry with the component named | |
| "path" will only contain: | | "path" will only contain: | |
| | | | |
| o rdattr_error (value: NFS_OK) | | o rdattr_error (value: NFS_OK) | |
| | | | |
| o fs_locations | | o fs_locations | |
| | | | |
| o mounted_on_fileid (value: unique fileid within referring file | | o mounted_on_fileid (value: unique fileid within referring file | |
| system) | | system) | |
| | | | |
| o fsid (value: unique value within referring server) | | o fsid (value: unique value within referring server) | |
|
| | | The attributes for entry "path" will not contain size or time_modify, | |
| The attributes for entry "path" will not contain size or time_modify | | | |
| because these attributes are not available within an absent file | | because these attributes are not available within an absent file | |
| system. | | system. | |
| | | | |
| 8.8. The Attribute fs_locations | | 8.8. The Attribute fs_locations | |
| | | | |
| The fs_locations attribute is defined by both fs_location4 | | The fs_locations attribute is defined by both fs_location4 | |
| (Section 2.2.6) and fs_locations4 (Section 2.2.7). It is used to | | (Section 2.2.6) and fs_locations4 (Section 2.2.7). It is used to | |
| represent the location of a file system by providing a server name | | represent the location of a file system by providing a server name | |
| and the path to the root of the file system within that server's | | and the path to the root of the file system within that server's | |
| namespace. When a set of servers have corresponding file systems at | | namespace. When a set of servers have corresponding file systems at | |
| the same path within their namespaces, an array of server names may | | the same path within their namespaces, an array of server names may | |
| be provided. An entry in the server array is a UTF-8 string and | | be provided. An entry in the server array is a UTF-8 string and | |
| represents one of a traditional DNS host name, IPv4 address, IPv6 | | represents one of a traditional DNS host name, IPv4 address, IPv6 | |
| address, or a zero-length string. A zero-length string SHOULD be | | address, or a zero-length string. A zero-length string SHOULD be | |
|
| used to indicate the current address being used for the RPC call. It | | used to indicate the current address being used for the RPC. It is | |
| is not a requirement that all servers that share the same rootpath be | | not a requirement that all servers that share the same rootpath be | |
| listed in one fs_location4 instance. The array of server names is | | listed in one fs_location4 instance. The array of server names is | |
| provided for convenience. Servers that share the same rootpath may | | provided for convenience. Servers that share the same rootpath may | |
| also be listed in separate fs_location4 entries in the fs_locations | | also be listed in separate fs_location4 entries in the fs_locations | |
| attribute. | | attribute. | |
| | | | |
| The fs_locations4 data type and fs_locations attribute contain an | | The fs_locations4 data type and fs_locations attribute contain an | |
| array of such locations. Since the namespace of each server may be | | array of such locations. Since the namespace of each server may be | |
|
| constructed differently, the "fs_root" field is provided. The path | | constructed differently, the fs_root field is provided. The path | |
| represented by fs_root represents the location of the file system in | | represented by the fs_root represents the location of the file system | |
| the current server's namespace, i.e., that of the server from which | | in the current server's namespace, i.e., that of the server from | |
| the fs_locations attribute was obtained. The fs_root path is meant | | which the fs_locations attribute was obtained. The fs_root path is | |
| to aid the client by clearly referencing the root of the file system | | meant to aid the client by clearly referencing the root of the file | |
| whose locations are being reported, no matter what object within the | | system whose locations are being reported, no matter what object | |
| current file system the current filehandle designates. The fs_root | | within the current file system the current filehandle designates. | |
| is simply the pathname the client used to reach the object on the | | The fs_root is simply the pathname the client used to reach the | |
| current server (i.e., the object to which the fs_locations attribute | | object on the current server (i.e., the object to which the | |
| applies). | | fs_locations attribute applies). | |
| | | | |
| When the fs_locations attribute is interrogated and there are no | | When the fs_locations attribute is interrogated and there are no | |
|
| alternative file system locations, the server SHOULD return a zero- | | alternative file system locations, the server SHOULD return a | |
| length array of fs_location4 structures, together with a valid | | zero-length array of fs_location4 structures, together with a | |
| fs_root. | | valid fs_root. | |
| | | | |
| As an example, suppose there is a replicated file system located at | | As an example, suppose there is a replicated file system located at | |
| two servers (servA and servB). At servA, the file system is located | | two servers (servA and servB). At servA, the file system is located | |
|
| at path /a/b/c. At, servB the file system is located at path /x/y/z. | | at path /a/b/c. At servB, the file system is located at path /x/y/z. | |
| If the client were to obtain the fs_locations value for the directory | | If the client were to obtain the fs_locations value for the directory | |
| at /a/b/c/d, it might not necessarily know that the file system's | | at /a/b/c/d, it might not necessarily know that the file system's | |
| root is located in servA's namespace at /a/b/c. When the client | | root is located in servA's namespace at /a/b/c. When the client | |
| switches to servB, it will need to determine that the directory it | | switches to servB, it will need to determine that the directory it | |
|
| first referenced at servA is now represented by the path /x/y/z/d on | | first referenced at servA is now represented by the path /x/y/z/d | |
| servB. To facilitate this, the fs_locations attribute provided by | | on servB. To facilitate this, the fs_locations attribute provided by | |
| servA would have an fs_root value of /a/b/c and two entries in | | servA would have an fs_root value of /a/b/c and two entries in | |
|
| fs_locations. One entry in fs_locations will be for itself (servA) | | fs_locations. One entry in fs_locations will be for itself (servA), | |
| and the other will be for servB with a path of /x/y/z. With this | | and the other will be for servB with a path of /x/y/z. With this | |
|
| information, the client is able to substitute /x/y/z for the /a/b/c | | information, the client is able to substitute /x/y/z for /a/b/c at | |
| at the beginning of its access path and construct /x/y/z/d to use for | | the beginning of its access path and construct /x/y/z/d to use for | |
| the new server. | | the new server. | |
| | | | |
|
| Note that: there is no requirement that the number of components in | | Note that there is no requirement that the number of components in | |
| each rootpath be the same; there is no relation between the number of | | each rootpath be the same; there is no relation between the number of | |
|
| components in rootpath or fs_root, and none of the components in each | | components in the rootpath or fs_root, and none of the components in | |
| rootpath and fs_root have to be the same. In the above example, we | | each rootpath and fs_root have to be the same. In the above example, | |
| could have had a third element in the locations array, with server | | we could have had a third element in the locations array, with server | |
| equal to "servC", and rootpath equal to "/I/II", and a fourth element | | equal to "servC" and rootpath equal to "/I/II", and a fourth element | |
| in locations with server equal to "servD" and rootpath equal to "/ | | in the locations array, with server equal to "servD" and rootpath | |
| aleph/beth/gimel/daleth/he". | | equal to "/aleph/beth/gimel/daleth/he". | |
| | | | |
|
| The relationship between fs_root to a rootpath is that the client | | The relationship between an fs_root and a rootpath is that the client | |
| replaces the pathname indicated in fs_root for the current server for | | replaces the pathname indicated in the fs_root for the current server | |
| the substitute indicated in rootpath for the new server. | | for the substitute indicated in the rootpath for the new server. | |
| | | | |
| For an example of a referred or migrated file system, suppose there | | For an example of a referred or migrated file system, suppose there | |
| is a file system located at serv1. At serv1, the file system is | | is a file system located at serv1. At serv1, the file system is | |
|
| located at /az/buky/vedi/glagoli. The client finds that object at | | located at /az/buky/vedi/glagoli. The client finds that the object | |
| glagoli has migrated (or is a referral). The client gets the | | at glagoli has migrated (or is a referral). The client gets the | |
| fs_locations attribute, which contains an fs_root of /az/buky/vedi/ | | fs_locations attribute, which contains an fs_root of /az/buky/vedi/ | |
| glagoli, and one element in the locations array, with server equal to | | glagoli, and one element in the locations array, with server equal to | |
|
| serv2, and rootpath equal to /izhitsa/fita. The client replaces /az/ | | serv2, and rootpath equal to /izhitsa/fita. The client replaces | |
| buky/vedi/glagoli with /izhitsa/fita, and uses the latter pathname on | | /az/buky/vedi/glagoli with /izhitsa/fita and uses the latter pathname | |
| serv2. | | on serv2. | |
| | | | |
| Thus, the server MUST return an fs_root that is equal to the path the | | Thus, the server MUST return an fs_root that is equal to the path the | |
| client used to reach the object to which the fs_locations attribute | | client used to reach the object to which the fs_locations attribute | |
| applies. Otherwise, the client cannot determine the new path to use | | applies. Otherwise, the client cannot determine the new path to use | |
| on the new server. | | on the new server. | |
| | | | |
| 9. File Locking and Share Reservations | | 9. File Locking and Share Reservations | |
| | | | |
| Integrating locking into the NFS protocol necessarily causes it to be | | Integrating locking into the NFS protocol necessarily causes it to be | |
|
| stateful. With the inclusion of share reservations the protocol | | stateful. With the inclusion of share reservations, the protocol | |
| becomes substantially more dependent on state than the traditional | | becomes substantially more dependent on state than the traditional | |
| combination of NFS and NLM (Network Lock Manager) [xnfs]. There are | | combination of NFS and NLM (Network Lock Manager) [xnfs]. There are | |
| three components to making this state manageable: | | three components to making this state manageable: | |
| | | | |
| o clear division between client and server | | o clear division between client and server | |
| | | | |
| o ability to reliably detect inconsistency in state between client | | o ability to reliably detect inconsistency in state between client | |
| and server | | and server | |
| | | | |
| o simple and robust recovery mechanisms | | o simple and robust recovery mechanisms | |
| | | | |
| In this model, the server owns the state information. The client | | In this model, the server owns the state information. The client | |
|
| requests changes in locks and the server responds with the changes | | requests changes in locks, and the server responds with the changes | |
| made. Non-client-initiated changes in locking state are infrequent. | | made. Non-client-initiated changes in locking state are infrequent. | |
| The client receives prompt notification of such changes and can | | The client receives prompt notification of such changes and can | |
| adjust its view of the locking state to reflect the server's changes. | | adjust its view of the locking state to reflect the server's changes. | |
| | | | |
| Individual pieces of state created by the server and passed to the | | Individual pieces of state created by the server and passed to the | |
| client at its request are represented by 128-bit stateids. These | | client at its request are represented by 128-bit stateids. These | |
| stateids may represent a particular open file, a set of byte-range | | stateids may represent a particular open file, a set of byte-range | |
| locks held by a particular owner, or a recallable delegation of | | locks held by a particular owner, or a recallable delegation of | |
| privileges to access a file in particular ways or at a particular | | privileges to access a file in particular ways or at a particular | |
| location. | | location. | |
| | | | |
| In all cases, there is a transition from the most general information | | In all cases, there is a transition from the most general information | |
| that represents a client as a whole to the eventual lightweight | | that represents a client as a whole to the eventual lightweight | |
| stateid used for most client and server locking interactions. The | | stateid used for most client and server locking interactions. The | |
|
| details of this transition will vary with the type of object but it | | details of this transition will vary with the type of object, but it | |
| always starts with a client ID. | | always starts with a client ID. | |
| | | | |
|
| To support Win32 share reservations it is necessary to atomically | | To support Win32 share reservations, it is necessary to atomically | |
| OPEN or CREATE files and apply the appropriate locks in the same | | OPEN or CREATE files and apply the appropriate locks in the same | |
| operation. Having a separate share/unshare operation would not allow | | operation. Having a separate share/unshare operation would not allow | |
| correct implementation of the Win32 OpenFile API. In order to | | correct implementation of the Win32 OpenFile API. In order to | |
| correctly implement share semantics, the previous NFS protocol | | correctly implement share semantics, the previous NFS protocol | |
| mechanisms used when a file is opened or created (LOOKUP, CREATE, | | mechanisms used when a file is opened or created (LOOKUP, CREATE, | |
| ACCESS) need to be replaced. The NFSv4 protocol has an OPEN | | ACCESS) need to be replaced. The NFSv4 protocol has an OPEN | |
| operation that subsumes the NFSv3 methodology of LOOKUP, CREATE, and | | operation that subsumes the NFSv3 methodology of LOOKUP, CREATE, and | |
| ACCESS. However, because many operations require a filehandle, the | | ACCESS. However, because many operations require a filehandle, the | |
|
| traditional LOOKUP is preserved to map a file name to filehandle | | traditional LOOKUP is preserved to map a filename to a filehandle | |
| without establishing state on the server. The policy of granting | | without establishing state on the server. The policy of granting | |
| access or modifying files is managed by the server based on the | | access or modifying files is managed by the server based on the | |
| client's state. These mechanisms can implement policy ranging from | | client's state. These mechanisms can implement policy ranging from | |
| advisory only locking to full mandatory locking. | | advisory only locking to full mandatory locking. | |
| | | | |
| 9.1. Opens and Byte-Range Locks | | 9.1. Opens and Byte-Range Locks | |
| | | | |
| It is assumed that manipulating a byte-range lock is rare when | | It is assumed that manipulating a byte-range lock is rare when | |
| compared to READ and WRITE operations. It is also assumed that | | compared to READ and WRITE operations. It is also assumed that | |
| server restarts and network partitions are relatively rare. | | server restarts and network partitions are relatively rare. | |
|
| Therefore it is important that the READ and WRITE operations have a | | Therefore, it is important that the READ and WRITE operations have a | |
| lightweight mechanism to indicate if they possess a held lock. A | | lightweight mechanism to indicate if they possess a held lock. A | |
| byte-range lock request contains the heavyweight information required | | byte-range lock request contains the heavyweight information required | |
| to establish a lock and uniquely define the owner of the lock. | | to establish a lock and uniquely define the owner of the lock. | |
| | | | |
|
| The following sections describe the transition from the heavy weight | | The following sections describe the transition from the heavyweight | |
| information to the eventual stateid used for most client and server | | information to the eventual stateid used for most client and server | |
| locking and lease interactions. | | locking and lease interactions. | |
| | | | |
| 9.1.1. Client ID | | 9.1.1. Client ID | |
| | | | |
| For each LOCK request, the client must identify itself to the server. | | For each LOCK request, the client must identify itself to the server. | |
| This is done in such a way as to allow for correct lock | | This is done in such a way as to allow for correct lock | |
| identification and crash recovery. A sequence of a SETCLIENTID | | identification and crash recovery. A sequence of a SETCLIENTID | |
| operation followed by a SETCLIENTID_CONFIRM operation is required to | | operation followed by a SETCLIENTID_CONFIRM operation is required to | |
| establish the identification onto the server. Establishment of | | establish the identification onto the server. Establishment of | |
| identification by a new incarnation of the client also has the effect | | identification by a new incarnation of the client also has the effect | |
| of immediately breaking any leased state that a previous incarnation | | of immediately breaking any leased state that a previous incarnation | |
| of the client might have had on the server, as opposed to forcing the | | of the client might have had on the server, as opposed to forcing the | |
| new client incarnation to wait for the leases to expire. Breaking | | new client incarnation to wait for the leases to expire. Breaking | |
| the lease state amounts to the server removing all lock, share | | the lease state amounts to the server removing all lock, share | |
| reservation, and, where the server is not supporting the | | reservation, and, where the server is not supporting the | |
| CLAIM_DELEGATE_PREV claim type, all delegation state associated with | | CLAIM_DELEGATE_PREV claim type, all delegation state associated with | |
|
| same client with the same identity. For discussion of delegation | | the same client with the same identity. For a discussion of | |
| state recovery, see Section 10.2.1. | | delegation state recovery, see Section 10.2.1. | |
| |