draft-ietf-nfsv4-rfc3530bis-13.txt   draft-ietf-nfsv4-rfc3530bis-14.txt 
NFSv4 T. Haynes, Ed. NFSv4 T. Haynes, Ed.
Internet-Draft NetApp Internet-Draft NetApp
Intended status: Standards Track D. Noveck, Ed. Intended status: Standards Track D. Noveck, Ed.
Expires: February 17, 2012 EMC Expires: March 5, 2012 EMC
August 16, 2011 September 02, 2011
Network File System (NFS) Version 4 Protocol Network File System (NFS) Version 4 Protocol
draft-ietf-nfsv4-rfc3530bis-13.txt draft-ietf-nfsv4-rfc3530bis-14.txt
Abstract Abstract
The Network File System (NFS) version 4 is a distributed filesystem The Network File System (NFS) version 4 is a distributed filesystem
protocol which owes heritage to NFS protocol version 2, RFC 1094, and protocol which owes heritage to NFS protocol version 2, RFC 1094, and
version 3, RFC 1813. Unlike earlier versions, the NFS version 4 version 3, RFC 1813. Unlike earlier versions, the NFS version 4
protocol supports traditional file access while integrating support protocol supports traditional file access while integrating support
for file locking and the mount protocol. In addition, support for for file locking and the mount protocol. In addition, support for
strong security (and its negotiation), compound operations, client strong security (and its negotiation), compound operations, client
caching, and internationalization have been added. Of course, caching, and internationalization have been added. Of course,
skipping to change at page 1, line 49 skipping to change at page 1, line 49
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on February 17, 2012. This Internet-Draft will expire on March 5, 2012.
Copyright Notice Copyright Notice
Copyright (c) 2011 IETF Trust and the persons identified as the Copyright (c) 2011 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
skipping to change at page 3, line 9 skipping to change at page 3, line 9
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 . . . . . . . . . . . . . . . . . . . . . . . . 9 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 9
1.1. Changes since RFC 3530 . . . . . . . . . . . . . . . . . 9 1.1. Changes since RFC 3530 . . . . . . . . . . . . . . . . . 9
1.2. Changes since RFC 3010 . . . . . . . . . . . . . . . . . 10 1.2. Changes since RFC 3010 . . . . . . . . . . . . . . . . . 9
1.3. NFS Version 4 Goals . . . . . . . . . . . . . . . . . . 11 1.3. NFS Version 4 Goals . . . . . . . . . . . . . . . . . . 11
1.4. Inconsistencies of this Document with the companion 1.4. Inconsistencies of this Document with the companion
document NFS Version 4 Protocol . . . . . . . . . . . . 11 document NFS Version 4 Protocol . . . . . . . . . . . . 11
1.5. Overview of NFSv4 Features . . . . . . . . . . . . . . . 12 1.5. Overview of NFSv4 Features . . . . . . . . . . . . . . . 12
1.5.1. RPC and Security . . . . . . . . . . . . . . . . . . 12 1.5.1. RPC and Security . . . . . . . . . . . . . . . . . . 12
1.5.2. Procedure and Operation Structure . . . . . . . . . 12 1.5.2. Procedure and Operation Structure . . . . . . . . . 12
1.5.3. Filesystem Model . . . . . . . . . . . . . . . . . . 13 1.5.3. Filesystem Model . . . . . . . . . . . . . . . . . . 13
1.5.4. OPEN and CLOSE . . . . . . . . . . . . . . . . . . . 15 1.5.4. OPEN and CLOSE . . . . . . . . . . . . . . . . . . . 15
1.5.5. File Locking . . . . . . . . . . . . . . . . . . . . 15 1.5.5. File Locking . . . . . . . . . . . . . . . . . . . . 15
1.5.6. Client Caching and Delegation . . . . . . . . . . . 15 1.5.6. Client Caching and Delegation . . . . . . . . . . . 15
skipping to change at page 3, line 36 skipping to change at page 3, line 36
3.1.1. Client Retransmission Behavior . . . . . . . . . . . 26 3.1.1. Client Retransmission Behavior . . . . . . . . . . . 26
3.2. Security Flavors . . . . . . . . . . . . . . . . . . . . 27 3.2. Security Flavors . . . . . . . . . . . . . . . . . . . . 27
3.2.1. Security mechanisms for NFSv4 . . . . . . . . . . . 27 3.2.1. Security mechanisms for NFSv4 . . . . . . . . . . . 27
3.3. Security Negotiation . . . . . . . . . . . . . . . . . . 28 3.3. Security Negotiation . . . . . . . . . . . . . . . . . . 28
3.3.1. SECINFO . . . . . . . . . . . . . . . . . . . . . . 28 3.3.1. SECINFO . . . . . . . . . . . . . . . . . . . . . . 28
3.3.2. Security Error . . . . . . . . . . . . . . . . . . . 28 3.3.2. Security Error . . . . . . . . . . . . . . . . . . . 28
3.3.3. Callback RPC Authentication . . . . . . . . . . . . 29 3.3.3. Callback RPC Authentication . . . . . . . . . . . . 29
4. Filehandles . . . . . . . . . . . . . . . . . . . . . . . . . 30 4. Filehandles . . . . . . . . . . . . . . . . . . . . . . . . . 30
4.1. Obtaining the First Filehandle . . . . . . . . . . . . . 30 4.1. Obtaining the First Filehandle . . . . . . . . . . . . . 30
4.1.1. Root Filehandle . . . . . . . . . . . . . . . . . . 30 4.1.1. Root Filehandle . . . . . . . . . . . . . . . . . . 30
4.1.2. Public Filehandle . . . . . . . . . . . . . . . . . 31 4.1.2. Public Filehandle . . . . . . . . . . . . . . . . . 30
4.2. Filehandle Types . . . . . . . . . . . . . . . . . . . . 31 4.2. Filehandle Types . . . . . . . . . . . . . . . . . . . . 31
4.2.1. General Properties of a Filehandle . . . . . . . . . 31 4.2.1. General Properties of a Filehandle . . . . . . . . . 31
4.2.2. Persistent Filehandle . . . . . . . . . . . . . . . 32 4.2.2. Persistent Filehandle . . . . . . . . . . . . . . . 32
4.2.3. Volatile Filehandle . . . . . . . . . . . . . . . . 32 4.2.3. Volatile Filehandle . . . . . . . . . . . . . . . . 32
4.2.4. One Method of Constructing a Volatile Filehandle . . 34 4.2.4. One Method of Constructing a Volatile Filehandle . . 34
4.3. Client Recovery from Filehandle Expiration . . . . . . . 34 4.3. Client Recovery from Filehandle Expiration . . . . . . . 34
5. File Attributes . . . . . . . . . . . . . . . . . . . . . . . 35 5. File Attributes . . . . . . . . . . . . . . . . . . . . . . . 35
5.1. REQUIRED Attributes . . . . . . . . . . . . . . . . . . 36 5.1. REQUIRED Attributes . . . . . . . . . . . . . . . . . . 36
5.2. RECOMMENDED Attributes . . . . . . . . . . . . . . . . . 36 5.2. RECOMMENDED Attributes . . . . . . . . . . . . . . . . . 36
5.3. Named Attributes . . . . . . . . . . . . . . . . . . . . 37 5.3. Named Attributes . . . . . . . . . . . . . . . . . . . . 37
5.4. Classification of Attributes . . . . . . . . . . . . . . 38 5.4. Classification of Attributes . . . . . . . . . . . . . . 38
5.5. Set-Only and Get-Only Attributes . . . . . . . . . . . . 39 5.5. Set-Only and Get-Only Attributes . . . . . . . . . . . . 39
5.6. REQUIRED Attributes - List and Definition References . . 39 5.6. REQUIRED Attributes - List and Definition References . . 39
5.7. RECOMMENDED Attributes - List and Definition 5.7. RECOMMENDED Attributes - List and Definition
References . . . . . . . . . . . . . . . . . . . . . . . 40 References . . . . . . . . . . . . . . . . . . . . . . . 40
5.8. Attribute Definitions . . . . . . . . . . . . . . . . . 41 5.8. Attribute Definitions . . . . . . . . . . . . . . . . . 41
5.8.1. Definitions of REQUIRED Attributes . . . . . . . . . 41 5.8.1. Definitions of REQUIRED Attributes . . . . . . . . . 41
5.8.2. Definitions of Uncategorized RECOMMENDED 5.8.2. Definitions of Uncategorized RECOMMENDED
Attributes . . . . . . . . . . . . . . . . . . . . . 44 Attributes . . . . . . . . . . . . . . . . . . . . . 43
5.9. Interpreting owner and owner_group . . . . . . . . . . . 50 5.9. Interpreting owner and owner_group . . . . . . . . . . . 49
5.10. Character Case Attributes . . . . . . . . . . . . . . . 53 5.10. Character Case Attributes . . . . . . . . . . . . . . . 52
6. Access Control Attributes . . . . . . . . . . . . . . . . . . 53 6. Access Control Attributes . . . . . . . . . . . . . . . . . . 52
6.1. Goals . . . . . . . . . . . . . . . . . . . . . . . . . 53 6.1. Goals . . . . . . . . . . . . . . . . . . . . . . . . . 53
6.2. File Attributes Discussion . . . . . . . . . . . . . . . 54 6.2. File Attributes Discussion . . . . . . . . . . . . . . . 53
6.2.1. Attribute 12: acl . . . . . . . . . . . . . . . . . 54 6.2.1. Attribute 12: acl . . . . . . . . . . . . . . . . . 53
6.2.2. Attribute 33: mode . . . . . . . . . . . . . . . . . 68 6.2.2. Attribute 33: mode . . . . . . . . . . . . . . . . . 68
6.3. Common Methods . . . . . . . . . . . . . . . . . . . . . 69 6.3. Common Methods . . . . . . . . . . . . . . . . . . . . . 68
6.3.1. Interpreting an ACL . . . . . . . . . . . . . . . . 69 6.3.1. Interpreting an ACL . . . . . . . . . . . . . . . . 68
6.3.2. Computing a Mode Attribute from an ACL . . . . . . . 70 6.3.2. Computing a Mode Attribute from an ACL . . . . . . . 69
6.4. Requirements . . . . . . . . . . . . . . . . . . . . . . 71 6.4. Requirements . . . . . . . . . . . . . . . . . . . . . . 70
6.4.1. Setting the mode and/or ACL Attributes . . . . . . . 71 6.4.1. Setting the mode and/or ACL Attributes . . . . . . . 71
6.4.2. Retrieving the mode and/or ACL Attributes . . . . . 73 6.4.2. Retrieving the mode and/or ACL Attributes . . . . . 72
6.4.3. Creating New Objects . . . . . . . . . . . . . . . . 73 6.4.3. Creating New Objects . . . . . . . . . . . . . . . . 72
7. Multi-Server Namespace . . . . . . . . . . . . . . . . . . . 75 7. Multi-Server Namespace . . . . . . . . . . . . . . . . . . . 74
7.1. Location Attributes . . . . . . . . . . . . . . . . . . 75 7.1. Location Attributes . . . . . . . . . . . . . . . . . . 74
7.2. File System Presence or Absence . . . . . . . . . . . . 75 7.2. File System Presence or Absence . . . . . . . . . . . . 75
7.3. Getting Attributes for an Absent File System . . . . . . 76 7.3. Getting Attributes for an Absent File System . . . . . . 76
7.3.1. GETATTR Within an Absent File System . . . . . . . . 77 7.3.1. GETATTR Within an Absent File System . . . . . . . . 76
7.3.2. READDIR and Absent File Systems . . . . . . . . . . 78 7.3.2. READDIR and Absent File Systems . . . . . . . . . . 77
7.4. Uses of Location Information . . . . . . . . . . . . . . 78 7.4. Uses of Location Information . . . . . . . . . . . . . . 77
7.4.1. File System Replication . . . . . . . . . . . . . . 79 7.4.1. File System Replication . . . . . . . . . . . . . . 78
7.4.2. File System Migration . . . . . . . . . . . . . . . 80 7.4.2. File System Migration . . . . . . . . . . . . . . . 79
7.4.3. Referrals . . . . . . . . . . . . . . . . . . . . . 80 7.4.3. Referrals . . . . . . . . . . . . . . . . . . . . . 80
7.5. Location Entries and Server Identity . . . . . . . . . . 81 7.5. Location Entries and Server Identity . . . . . . . . . . 80
7.6. Additional Client-Side Considerations . . . . . . . . . 82 7.6. Additional Client-Side Considerations . . . . . . . . . 81
7.7. Effecting File System Transitions . . . . . . . . . . . 83 7.7. Effecting File System Transitions . . . . . . . . . . . 82
7.7.1. File System Transitions and Simultaneous Access . . 84 7.7.1. File System Transitions and Simultaneous Access . . 83
7.7.2. Filehandles and File System Transitions . . . . . . 84 7.7.2. Filehandles and File System Transitions . . . . . . 84
7.7.3. Fileids and File System Transitions . . . . . . . . 85 7.7.3. Fileids and File System Transitions . . . . . . . . 84
7.7.4. Fsids and File System Transitions . . . . . . . . . 86 7.7.4. Fsids and File System Transitions . . . . . . . . . 85
7.7.5. The Change Attribute and File System Transitions . . 86 7.7.5. The Change Attribute and File System Transitions . . 86
7.7.6. Lock State and File System Transitions . . . . . . . 87 7.7.6. Lock State and File System Transitions . . . . . . . 86
7.7.7. Write Verifiers and File System Transitions . . . . 89 7.7.7. Write Verifiers and File System Transitions . . . . 88
7.7.8. Readdir Cookies and Verifiers and File System 7.7.8. Readdir Cookies and Verifiers and File System
Transitions . . . . . . . . . . . . . . . . . . . . 89 Transitions . . . . . . . . . . . . . . . . . . . . 88
7.7.9. File System Data and File System Transitions . . . . 89 7.7.9. File System Data and File System Transitions . . . . 89
7.8. Effecting File System Referrals . . . . . . . . . . . . 91 7.8. Effecting File System Referrals . . . . . . . . . . . . 90
7.8.1. Referral Example (LOOKUP) . . . . . . . . . . . . . 91 7.8.1. Referral Example (LOOKUP) . . . . . . . . . . . . . 90
7.8.2. Referral Example (READDIR) . . . . . . . . . . . . . 95 7.8.2. Referral Example (READDIR) . . . . . . . . . . . . . 94
7.9. The Attribute fs_locations . . . . . . . . . . . . . . . 97 7.9. The Attribute fs_locations . . . . . . . . . . . . . . . 97
7.9.1. Inferring Transition Modes . . . . . . . . . . . . . 99 7.9.1. Inferring Transition Modes . . . . . . . . . . . . . 98
8. NFS Server Name Space . . . . . . . . . . . . . . . . . . . . 100 8. NFS Server Name Space . . . . . . . . . . . . . . . . . . . . 100
8.1. Server Exports . . . . . . . . . . . . . . . . . . . . . 101 8.1. Server Exports . . . . . . . . . . . . . . . . . . . . . 100
8.2. Browsing Exports . . . . . . . . . . . . . . . . . . . . 101 8.2. Browsing Exports . . . . . . . . . . . . . . . . . . . . 100
8.3. Server Pseudo Filesystem . . . . . . . . . . . . . . . . 101 8.3. Server Pseudo Filesystem . . . . . . . . . . . . . . . . 100
8.4. Multiple Roots . . . . . . . . . . . . . . . . . . . . . 102 8.4. Multiple Roots . . . . . . . . . . . . . . . . . . . . . 101
8.5. Filehandle Volatility . . . . . . . . . . . . . . . . . 102 8.5. Filehandle Volatility . . . . . . . . . . . . . . . . . 101
8.6. Exported Root . . . . . . . . . . . . . . . . . . . . . 102 8.6. Exported Root . . . . . . . . . . . . . . . . . . . . . 101
8.7. Mount Point Crossing . . . . . . . . . . . . . . . . . . 103 8.7. Mount Point Crossing . . . . . . . . . . . . . . . . . . 102
8.8. Security Policy and Name Space Presentation . . . . . . 103 8.8. Security Policy and Name Space Presentation . . . . . . 102
9. File Locking and Share Reservations . . . . . . . . . . . . . 104 9. File Locking and Share Reservations . . . . . . . . . . . . . 103
9.1. Opens and Byte-Range Locks . . . . . . . . . . . . . . . 105 9.1. Opens and Byte-Range Locks . . . . . . . . . . . . . . . 104
9.1.1. Client ID . . . . . . . . . . . . . . . . . . . . . 105 9.1.1. Client ID . . . . . . . . . . . . . . . . . . . . . 104
9.1.2. Server Release of Client ID . . . . . . . . . . . . 108 9.1.2. Server Release of Client ID . . . . . . . . . . . . 107
9.1.3. Stateid Definition . . . . . . . . . . . . . . . . . 109 9.1.3. Stateid Definition . . . . . . . . . . . . . . . . . 108
9.1.4. lock-owner . . . . . . . . . . . . . . . . . . . . . 116 9.1.4. lock-owner . . . . . . . . . . . . . . . . . . . . . 114
9.1.5. Use of the Stateid and Locking . . . . . . . . . . . 117 9.1.5. Use of the Stateid and Locking . . . . . . . . . . . 115
9.1.6. Sequencing of Lock Requests . . . . . . . . . . . . 119 9.1.6. Sequencing of Lock Requests . . . . . . . . . . . . 117
9.1.7. Recovery from Replayed Requests . . . . . . . . . . 120 9.1.7. Recovery from Replayed Requests . . . . . . . . . . 118
9.1.8. Interactions of multiple sequence values . . . . . . 120 9.1.8. Interactions of multiple sequence values . . . . . . 118
9.1.9. Releasing state-owner State . . . . . . . . . . . . 121 9.1.9. Releasing state-owner State . . . . . . . . . . . . 119
9.1.10. Use of Open Confirmation . . . . . . . . . . . . . . 122 9.1.10. Use of Open Confirmation . . . . . . . . . . . . . . 120
9.2. Lock Ranges . . . . . . . . . . . . . . . . . . . . . . 123 9.2. Lock Ranges . . . . . . . . . . . . . . . . . . . . . . 121
9.3. Upgrading and Downgrading Locks . . . . . . . . . . . . 124 9.3. Upgrading and Downgrading Locks . . . . . . . . . . . . 121
9.4. Blocking Locks . . . . . . . . . . . . . . . . . . . . . 124 9.4. Blocking Locks . . . . . . . . . . . . . . . . . . . . . 122
9.5. Lease Renewal . . . . . . . . . . . . . . . . . . . . . 125 9.5. Lease Renewal . . . . . . . . . . . . . . . . . . . . . 123
9.6. Crash Recovery . . . . . . . . . . . . . . . . . . . . . 126 9.6. Crash Recovery . . . . . . . . . . . . . . . . . . . . . 123
9.6.1. Client Failure and Recovery . . . . . . . . . . . . 126 9.6.1. Client Failure and Recovery . . . . . . . . . . . . 124
9.6.2. Server Failure and Recovery . . . . . . . . . . . . 127 9.6.2. Server Failure and Recovery . . . . . . . . . . . . 124
9.6.3. Network Partitions and Recovery . . . . . . . . . . 129 9.6.3. Network Partitions and Recovery . . . . . . . . . . 126
9.7. Recovery from a Lock Request Timeout or Abort . . . . . 135 9.7. Recovery from a Lock Request Timeout or Abort . . . . . 133
9.8. Server Revocation of Locks . . . . . . . . . . . . . . . 135 9.8. Server Revocation of Locks . . . . . . . . . . . . . . . 133
9.9. Share Reservations . . . . . . . . . . . . . . . . . . . 137 9.9. Share Reservations . . . . . . . . . . . . . . . . . . . 134
9.10. OPEN/CLOSE Operations . . . . . . . . . . . . . . . . . 137 9.10. OPEN/CLOSE Operations . . . . . . . . . . . . . . . . . 135
9.10.1. Close and Retention of State Information . . . . . . 138 9.10.1. Close and Retention of State Information . . . . . . 136
9.11. Open Upgrade and Downgrade . . . . . . . . . . . . . . . 139 9.11. Open Upgrade and Downgrade . . . . . . . . . . . . . . . 136
9.12. Short and Long Leases . . . . . . . . . . . . . . . . . 140 9.12. Short and Long Leases . . . . . . . . . . . . . . . . . 137
9.13. Clocks, Propagation Delay, and Calculating Lease 9.13. Clocks, Propagation Delay, and Calculating Lease
Expiration . . . . . . . . . . . . . . . . . . . . . . . 140 Expiration . . . . . . . . . . . . . . . . . . . . . . . 138
9.14. Migration, Replication and State . . . . . . . . . . . . 141 9.14. Migration, Replication and State . . . . . . . . . . . . 138
9.14.1. Migration and State . . . . . . . . . . . . . . . . 141 9.14.1. Migration and State . . . . . . . . . . . . . . . . 139
9.14.2. Replication and State . . . . . . . . . . . . . . . 142 9.14.2. Replication and State . . . . . . . . . . . . . . . 139
9.14.3. Notification of Migrated Lease . . . . . . . . . . . 142 9.14.3. Notification of Migrated Lease . . . . . . . . . . . 140
9.14.4. Migration and the Lease_time Attribute . . . . . . . 143 9.14.4. Migration and the Lease_time Attribute . . . . . . . 141
10. Client-Side Caching . . . . . . . . . . . . . . . . . . . . . 144 10. Client-Side Caching . . . . . . . . . . . . . . . . . . . . . 141
10.1. Performance Challenges for Client-Side Caching . . . . . 144 10.1. Performance Challenges for Client-Side Caching . . . . . 142
10.2. Delegation and Callbacks . . . . . . . . . . . . . . . . 145 10.2. Delegation and Callbacks . . . . . . . . . . . . . . . . 143
10.2.1. Delegation Recovery . . . . . . . . . . . . . . . . 147 10.2.1. Delegation Recovery . . . . . . . . . . . . . . . . 144
10.3. Data Caching . . . . . . . . . . . . . . . . . . . . . . 149 10.3. Data Caching . . . . . . . . . . . . . . . . . . . . . . 146
10.3.1. Data Caching and OPENs . . . . . . . . . . . . . . . 149 10.3.1. Data Caching and OPENs . . . . . . . . . . . . . . . 147
10.3.2. Data Caching and File Locking . . . . . . . . . . . 150 10.3.2. Data Caching and File Locking . . . . . . . . . . . 148
10.3.3. Data Caching and Mandatory File Locking . . . . . . 152 10.3.3. Data Caching and Mandatory File Locking . . . . . . 149
10.3.4. Data Caching and File Identity . . . . . . . . . . . 152 10.3.4. Data Caching and File Identity . . . . . . . . . . . 150
10.4. Open Delegation . . . . . . . . . . . . . . . . . . . . 153 10.4. Open Delegation . . . . . . . . . . . . . . . . . . . . 151
10.4.1. Open Delegation and Data Caching . . . . . . . . . . 156 10.4.1. Open Delegation and Data Caching . . . . . . . . . . 153
10.4.2. Open Delegation and File Locks . . . . . . . . . . . 157 10.4.2. Open Delegation and File Locks . . . . . . . . . . . 155
10.4.3. Handling of CB_GETATTR . . . . . . . . . . . . . . . 157 10.4.3. Handling of CB_GETATTR . . . . . . . . . . . . . . . 155
10.4.4. Recall of Open Delegation . . . . . . . . . . . . . 160 10.4.4. Recall of Open Delegation . . . . . . . . . . . . . 158
10.4.5. OPEN Delegation Race with CB_RECALL . . . . . . . . 162 10.4.5. OPEN Delegation Race with CB_RECALL . . . . . . . . 160
10.4.6. Clients that Fail to Honor Delegation Recalls . . . 163 10.4.6. Clients that Fail to Honor Delegation Recalls . . . 161
10.4.7. Delegation Revocation . . . . . . . . . . . . . . . 164 10.4.7. Delegation Revocation . . . . . . . . . . . . . . . 162
10.5. Data Caching and Revocation . . . . . . . . . . . . . . 164 10.5. Data Caching and Revocation . . . . . . . . . . . . . . 162
10.5.1. Revocation Recovery for Write Open Delegation . . . 165 10.5.1. Revocation Recovery for Write Open Delegation . . . 163
10.6. Attribute Caching . . . . . . . . . . . . . . . . . . . 165 10.6. Attribute Caching . . . . . . . . . . . . . . . . . . . 163
10.7. Data and Metadata Caching and Memory Mapped Files . . . 167 10.7. Data and Metadata Caching and Memory Mapped Files . . . 165
10.8. Name Caching . . . . . . . . . . . . . . . . . . . . . . 170 10.8. Name Caching . . . . . . . . . . . . . . . . . . . . . . 167
10.9. Directory Caching . . . . . . . . . . . . . . . . . . . 171 10.9. Directory Caching . . . . . . . . . . . . . . . . . . . 168
11. Minor Versioning . . . . . . . . . . . . . . . . . . . . . . 171 11. Minor Versioning . . . . . . . . . . . . . . . . . . . . . . 169
12. Internationalization . . . . . . . . . . . . . . . . . . . . 174 12. Internationalization . . . . . . . . . . . . . . . . . . . . 172
12.1. Use of UTF-8 . . . . . . . . . . . . . . . . . . . . . . 175 12.1. Use of UTF-8 . . . . . . . . . . . . . . . . . . . . . . 173
12.1.1. Relation to Stringprep . . . . . . . . . . . . . . . 175 12.1.1. Relation to Stringprep . . . . . . . . . . . . . . . 173
12.1.2. Normalization, Equivalence, and Confusability . . . 176 12.1.2. Normalization, Equivalence, and Confusability . . . 174
12.2. String Type Overview . . . . . . . . . . . . . . . . . . 179 12.2. String Type Overview . . . . . . . . . . . . . . . . . . 177
12.2.1. Overall String Class Divisions . . . . . . . . . . . 179 12.2.1. Overall String Class Divisions . . . . . . . . . . . 177
12.2.2. Divisions by Typedef Parent types . . . . . . . . . 180 12.2.2. Divisions by Typedef Parent types . . . . . . . . . 178
12.2.3. Individual Types and Their Handling . . . . . . . . 181 12.2.3. Individual Types and Their Handling . . . . . . . . 179
12.3. Errors Related to Strings . . . . . . . . . . . . . . . 182 12.3. Errors Related to Strings . . . . . . . . . . . . . . . 180
12.4. Types with Pre-processing to Resolve Mixture Issues . . 183 12.4. Types with Pre-processing to Resolve Mixture Issues . . 181
12.4.1. Processing of Principal Strings . . . . . . . . . . 183 12.4.1. Processing of Principal Strings . . . . . . . . . . 181
12.4.2. Processing of Server Id Strings . . . . . . . . . . 183 12.4.2. Processing of Server Id Strings . . . . . . . . . . 181
12.5. String Types without Internationalization Processing . . 184 12.5. String Types without Internationalization Processing . . 182
12.6. Types with Processing Defined by Other Internet Areas . 184 12.6. Types with Processing Defined by Other Internet Areas . 182
12.7. String Types with NFS-specific Processing . . . . . . . 185 12.7. String Types with NFS-specific Processing . . . . . . . 183
12.7.1. Handling of File Name Components . . . . . . . . . . 186 12.7.1. Handling of File Name Components . . . . . . . . . . 184
12.7.2. Processing of Link Text . . . . . . . . . . . . . . 195 12.7.2. Processing of Link Text . . . . . . . . . . . . . . 193
12.7.3. Processing of Principal Prefixes . . . . . . . . . . 196 12.7.3. Processing of Principal Prefixes . . . . . . . . . . 194
13. Error Values . . . . . . . . . . . . . . . . . . . . . . . . 197 13. Error Values . . . . . . . . . . . . . . . . . . . . . . . . 195
13.1. Error Definitions . . . . . . . . . . . . . . . . . . . 197 13.1. Error Definitions . . . . . . . . . . . . . . . . . . . 195
13.1.1. General Errors . . . . . . . . . . . . . . . . . . . 199 13.1.1. General Errors . . . . . . . . . . . . . . . . . . . 197
13.1.2. Filehandle Errors . . . . . . . . . . . . . . . . . 200 13.1.2. Filehandle Errors . . . . . . . . . . . . . . . . . 198
13.1.3. Compound Structure Errors . . . . . . . . . . . . . 201 13.1.3. Compound Structure Errors . . . . . . . . . . . . . 199
13.1.4. File System Errors . . . . . . . . . . . . . . . . . 202 13.1.4. File System Errors . . . . . . . . . . . . . . . . . 200
13.1.5. State Management Errors . . . . . . . . . . . . . . 204 13.1.5. State Management Errors . . . . . . . . . . . . . . 202
13.1.6. Security Errors . . . . . . . . . . . . . . . . . . 205 13.1.6. Security Errors . . . . . . . . . . . . . . . . . . 203
13.1.7. Name Errors . . . . . . . . . . . . . . . . . . . . 205 13.1.7. Name Errors . . . . . . . . . . . . . . . . . . . . 203
13.1.8. Locking Errors . . . . . . . . . . . . . . . . . . . 206 13.1.8. Locking Errors . . . . . . . . . . . . . . . . . . . 204
13.1.9. Reclaim Errors . . . . . . . . . . . . . . . . . . . 207 13.1.9. Reclaim Errors . . . . . . . . . . . . . . . . . . . 205
13.1.10. Client Management Errors . . . . . . . . . . . . . . 208 13.1.10. Client Management Errors . . . . . . . . . . . . . . 206
13.1.11. Attribute Handling Errors . . . . . . . . . . . . . 208 13.1.11. Attribute Handling Errors . . . . . . . . . . . . . 206
13.2. Operations and their valid errors . . . . . . . . . . . 209 13.2. Operations and their valid errors . . . . . . . . . . . 207
13.3. Callback operations and their valid errors . . . . . . . 216 13.3. Callback operations and their valid errors . . . . . . . 214
13.4. Errors and the operations that use them . . . . . . . . 216 13.4. Errors and the operations that use them . . . . . . . . 214
14. NFSv4 Requests . . . . . . . . . . . . . . . . . . . . . . . 221 14. NFSv4 Requests . . . . . . . . . . . . . . . . . . . . . . . 219
14.1. Compound Procedure . . . . . . . . . . . . . . . . . . . 221 14.1. Compound Procedure . . . . . . . . . . . . . . . . . . . 219
14.2. Evaluation of a Compound Request . . . . . . . . . . . . 222 14.2. Evaluation of a Compound Request . . . . . . . . . . . . 220
14.3. Synchronous Modifying Operations . . . . . . . . . . . . 223 14.3. Synchronous Modifying Operations . . . . . . . . . . . . 221
14.4. Operation Values . . . . . . . . . . . . . . . . . . . . 223 14.4. Operation Values . . . . . . . . . . . . . . . . . . . . 221
15. NFSv4 Procedures . . . . . . . . . . . . . . . . . . . . . . 223 15. NFSv4 Procedures . . . . . . . . . . . . . . . . . . . . . . 221
15.1. Procedure 0: NULL - No Operation . . . . . . . . . . . . 223 15.1. Procedure 0: NULL - No Operation . . . . . . . . . . . . 221
15.2. Procedure 1: COMPOUND - Compound Operations . . . . . . 224 15.2. Procedure 1: COMPOUND - Compound Operations . . . . . . 222
15.3. Operation 3: ACCESS - Check Access Rights . . . . . . . 229 15.3. Operation 3: ACCESS - Check Access Rights . . . . . . . 225
15.4. Operation 4: CLOSE - Close File . . . . . . . . . . . . 232 15.4. Operation 4: CLOSE - Close File . . . . . . . . . . . . 228
15.5. Operation 5: COMMIT - Commit Cached Data . . . . . . . . 233 15.5. Operation 5: COMMIT - Commit Cached Data . . . . . . . . 229
15.6. Operation 6: CREATE - Create a Non-Regular File Object . 235 15.6. Operation 6: CREATE - Create a Non-Regular File Object . 232
15.7. Operation 7: DELEGPURGE - Purge Delegations Awaiting 15.7. Operation 7: DELEGPURGE - Purge Delegations Awaiting
Recovery . . . . . . . . . . . . . . . . . . . . . . . . 238 Recovery . . . . . . . . . . . . . . . . . . . . . . . . 234
15.8. Operation 8: DELEGRETURN - Return Delegation . . . . . . 239 15.8. Operation 8: DELEGRETURN - Return Delegation . . . . . . 235
15.9. Operation 9: GETATTR - Get Attributes . . . . . . . . . 239 15.9. Operation 9: GETATTR - Get Attributes . . . . . . . . . 236
15.10. Operation 10: GETFH - Get Current Filehandle . . . . . . 241 15.10. Operation 10: GETFH - Get Current Filehandle . . . . . . 238
15.11. Operation 11: LINK - Create Link to a File . . . . . . . 242 15.11. Operation 11: LINK - Create Link to a File . . . . . . . 239
15.12. Operation 12: LOCK - Create Lock . . . . . . . . . . . . 243 15.12. Operation 12: LOCK - Create Lock . . . . . . . . . . . . 240
15.13. Operation 13: LOCKT - Test For Lock . . . . . . . . . . 247 15.13. Operation 13: LOCKT - Test For Lock . . . . . . . . . . 244
15.14. Operation 14: LOCKU - Unlock File . . . . . . . . . . . 249 15.14. Operation 14: LOCKU - Unlock File . . . . . . . . . . . 246
15.15. Operation 15: LOOKUP - Lookup Filename . . . . . . . . . 250 15.15. Operation 15: LOOKUP - Lookup Filename . . . . . . . . . 247
15.16. Operation 16: LOOKUPP - Lookup Parent Directory . . . . 252 15.16. Operation 16: LOOKUPP - Lookup Parent Directory . . . . 249
15.17. Operation 17: NVERIFY - Verify Difference in 15.17. Operation 17: NVERIFY - Verify Difference in
Attributes . . . . . . . . . . . . . . . . . . . . . . . 253 Attributes . . . . . . . . . . . . . . . . . . . . . . . 250
15.18. Operation 18: OPEN - Open a Regular File . . . . . . . . 254 15.18. Operation 18: OPEN - Open a Regular File . . . . . . . . 251
15.19. Operation 19: OPENATTR - Open Named Attribute 15.19. Operation 19: OPENATTR - Open Named Attribute
Directory . . . . . . . . . . . . . . . . . . . . . . . 264 Directory . . . . . . . . . . . . . . . . . . . . . . . 261
15.20. Operation 20: OPEN_CONFIRM - Confirm Open . . . . . . . 265 15.20. Operation 20: OPEN_CONFIRM - Confirm Open . . . . . . . 262
15.21. Operation 21: OPEN_DOWNGRADE - Reduce Open File Access . 267 15.21. Operation 21: OPEN_DOWNGRADE - Reduce Open File Access . 264
15.22. Operation 22: PUTFH - Set Current Filehandle . . . . . . 268 15.22. Operation 22: PUTFH - Set Current Filehandle . . . . . . 265
15.23. Operation 23: PUTPUBFH - Set Public Filehandle . . . . . 269 15.23. Operation 23: PUTPUBFH - Set Public Filehandle . . . . . 266
15.24. Operation 24: PUTROOTFH - Set Root Filehandle . . . . . 270 15.24. Operation 24: PUTROOTFH - Set Root Filehandle . . . . . 268
15.25. Operation 25: READ - Read from File . . . . . . . . . . 271 15.25. Operation 25: READ - Read from File . . . . . . . . . . 268
15.26. Operation 26: READDIR - Read Directory . . . . . . . . . 273 15.26. Operation 26: READDIR - Read Directory . . . . . . . . . 270
15.27. Operation 27: READLINK - Read Symbolic Link . . . . . . 277 15.27. Operation 27: READLINK - Read Symbolic Link . . . . . . 274
15.28. Operation 28: REMOVE - Remove Filesystem Object . . . . 278 15.28. Operation 28: REMOVE - Remove Filesystem Object . . . . 275
15.29. Operation 29: RENAME - Rename Directory Entry . . . . . 280 15.29. Operation 29: RENAME - Rename Directory Entry . . . . . 277
15.30. Operation 30: RENEW - Renew a Lease . . . . . . . . . . 282 15.30. Operation 30: RENEW - Renew a Lease . . . . . . . . . . 279
15.31. Operation 31: RESTOREFH - Restore Saved Filehandle . . . 283 15.31. Operation 31: RESTOREFH - Restore Saved Filehandle . . . 280
15.32. Operation 32: SAVEFH - Save Current Filehandle . . . . . 284 15.32. Operation 32: SAVEFH - Save Current Filehandle . . . . . 281
15.33. Operation 33: SECINFO - Obtain Available Security . . . 285 15.33. Operation 33: SECINFO - Obtain Available Security . . . 282
15.34. Operation 34: SETATTR - Set Attributes . . . . . . . . . 288 15.34. Operation 34: SETATTR - Set Attributes . . . . . . . . . 285
15.35. Operation 35: SETCLIENTID - Negotiate Client ID . . . . 291 15.35. Operation 35: SETCLIENTID - Negotiate Client ID . . . . 288
15.36. Operation 36: SETCLIENTID_CONFIRM - Confirm Client ID . 294 15.36. Operation 36: SETCLIENTID_CONFIRM - Confirm Client ID . 291
15.37. Operation 37: VERIFY - Verify Same Attributes . . . . . 298 15.37. Operation 37: VERIFY - Verify Same Attributes . . . . . 295
15.38. Operation 38: WRITE - Write to File . . . . . . . . . . 299 15.38. Operation 38: WRITE - Write to File . . . . . . . . . . 296
15.39. Operation 39: RELEASE_LOCKOWNER - Release Lockowner 15.39. Operation 39: RELEASE_LOCKOWNER - Release Lockowner
State . . . . . . . . . . . . . . . . . . . . . . . . . 303 State . . . . . . . . . . . . . . . . . . . . . . . . . 300
15.40. Operation 10044: ILLEGAL - Illegal operation . . . . . . 304 15.40. Operation 10044: ILLEGAL - Illegal operation . . . . . . 301
16. NFSv4 Callback Procedures . . . . . . . . . . . . . . . . . . 305 16. NFSv4 Callback Procedures . . . . . . . . . . . . . . . . . . 302
16.1. Procedure 0: CB_NULL - No Operation . . . . . . . . . . 305 16.1. Procedure 0: CB_NULL - No Operation . . . . . . . . . . 302
16.2. Procedure 1: CB_COMPOUND - Compound Operations . . . . . 306 16.2. Procedure 1: CB_COMPOUND - Compound Operations . . . . . 303
16.2.6. Operation 3: CB_GETATTR - Get Attributes . . . . . . 308 16.2.6. Operation 3: CB_GETATTR - Get Attributes . . . . . . 305
16.2.7. Operation 4: CB_RECALL - Recall an Open Delegation . 309 16.2.7. Operation 4: CB_RECALL - Recall an Open Delegation . 306
16.2.8. Operation 10044: CB_ILLEGAL - Illegal Callback 16.2.8. Operation 10044: CB_ILLEGAL - Illegal Callback
Operation . . . . . . . . . . . . . . . . . . . . . 310 Operation . . . . . . . . . . . . . . . . . . . . . 307
17. Security Considerations . . . . . . . . . . . . . . . . . . . 310 17. Security Considerations . . . . . . . . . . . . . . . . . . . 307
18. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 312 18. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 309
18.1. Named Attribute Definitions . . . . . . . . . . . . . . 312 18.1. Named Attribute Definitions . . . . . . . . . . . . . . 309
18.1.1. Initial Registry . . . . . . . . . . . . . . . . . . 313 18.1.1. Initial Registry . . . . . . . . . . . . . . . . . . 310
18.1.2. Updating Registrations . . . . . . . . . . . . . . . 313 18.1.2. Updating Registrations . . . . . . . . . . . . . . . 310
18.2. ONC RPC Network Identifiers (netids) . . . . . . . . . . 313 18.2. ONC RPC Network Identifiers (netids) . . . . . . . . . . 310
18.2.1. Initial Registry . . . . . . . . . . . . . . . . . . 314 18.2.1. Initial Registry . . . . . . . . . . . . . . . . . . 311
18.2.2. Updating Registrations . . . . . . . . . . . . . . . 314 18.2.2. Updating Registrations . . . . . . . . . . . . . . . 311
19. References . . . . . . . . . . . . . . . . . . . . . . . . . 315 19. References . . . . . . . . . . . . . . . . . . . . . . . . . 312
19.1. Normative References . . . . . . . . . . . . . . . . . . 315 19.1. Normative References . . . . . . . . . . . . . . . . . . 312
19.2. Informative References . . . . . . . . . . . . . . . . . 315 19.2. Informative References . . . . . . . . . . . . . . . . . 312
Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 318 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 315
Appendix B. RFC Editor Notes . . . . . . . . . . . . . . . . . . 318 Appendix B. RFC Editor Notes . . . . . . . . . . . . . . . . . . 315
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 319 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 316
1. Introduction 1. Introduction
1.1. Changes since RFC 3530 1.1. Changes since RFC 3530
This document, together with the companion XDR description document This document, together with the companion XDR description document
[2], obsoletes RFC 3530 [10] as the authoritative document describing [2], obsoletes RFC 3530 [10] as the authoritative document describing
NFSv4. It does not introduce any over-the-wire protocol changes, in NFSv4. It does not introduce any over-the-wire protocol changes, in
the sense that previously valid requests requests remain valid. the sense that previously valid requests requests remain valid.
However, some requests previously defined as invalid, although not However, some requests previously defined as invalid, although not
skipping to change at page 9, line 37 skipping to change at page 9, line 37
o More liberal handling of internationalization for file names and o More liberal handling of internationalization for file names and
user and group names, with the elimination of restrictions imposed user and group names, with the elimination of restrictions imposed
by stringprep, with the recognition that rules for the forms of by stringprep, with the recognition that rules for the forms of
these name are the province of the receiving entity. these name are the province of the receiving entity.
o Updating handling of domain names to reflect IDNA [3]. o Updating handling of domain names to reflect IDNA [3].
o Restructuring of string types to more appropriately reflect the o Restructuring of string types to more appropriately reflect the
reality of required string processing. reality of required string processing.
o LIPKEY SPKM/3 has been moved from being REQUIRED to being removed. o The previously required LIPKEY and SPKM-3 security mechanisms have
been removed.
o Some clarification on a client re-establishing callback o Some clarification on a client re-establishing callback
information to the new server if state has been migrated. 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, which had the side o The definition of stateid was strengthened.
effect of introducing a semantic change in a COMPOUND structure
having a current stateid and a saved stateid.
1.2. Changes since RFC 3010 1.2. Changes since RFC 3010
This definition of the NFSv4 protocol replaces or obsoletes the This definition of the NFSv4 protocol replaces or obsoletes the
definition present in [11]. While portions of the two documents have definition present in [11]. While portions of the two documents have
remained the same, there have been substantive changes in others. remained the same, there have been substantive changes in others.
The changes made between [11] and this document represent The changes made between [11] and this document represent
implementation experience and further review of the protocol. While implementation experience and further review of the protocol. While
some modifications were made for ease of implementation or some modifications were made for ease of implementation or
clarification, most updates represent errors or situations where the clarification, most updates represent errors or situations where the
[11] definition were untenable. [11] definition were untenable.
The following list is not all inclusive of all changes but presents The following list is not all inclusive of all changes but presents
some of the most notable changes or additions made: some 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
skipping to change at page 12, line 17 skipping to change at page 12, line 12
document that is inconsistent with [2], [2] is to be considered document that is inconsistent with [2], [2] is to be considered
authoritative. authoritative.
1.5. Overview of NFSv4 Features 1.5. 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 NFSv4 protocol will be reviewed in brief. This will be 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 that is with the previous versions of the NFS protocol and the reader that is
new to the NFS protocols. For the reader new to the NFS protocols, new to the NFS protocols. For the reader new to the NFS protocols,
there is still a fundamental knowledge that is expected. The reader some fundamental knowledge is still expected. The reader should be
should be familiar with the XDR and RPC protocols as described in [4] familiar with the XDR and RPC protocols as described in [4] and [14].
and [14]. A basic knowledge of filesystems and distributed A basic knowledge of filesystems and distributed filesystems is
filesystems is expected as well. expected as well.
1.5.1. RPC and Security 1.5.1. RPC and Security
As with previous versions of NFS, the External Data Representation As with previous versions of NFS, the External Data Representation
(XDR) and Remote Procedure Call (RPC) mechanisms used for the NFSv4 (XDR) and Remote Procedure Call (RPC) mechanisms used for the NFSv4
protocol are those defined in [4] and [14]. To meet end to end protocol are those defined in [4] and [14]. To meet end to end
security requirements, the RPCSEC_GSS framework [5] will be used to security requirements, the RPCSEC_GSS framework [5] will be used to
extend the basic RPC security. With the use of RPCSEC_GSS, various extend the basic RPC security. With the use of RPCSEC_GSS, various
mechanisms can be provided to offer authentication, integrity, and mechanisms can be provided to offer authentication, integrity, and
privacy to the NFS version 4 protocol. Kerberos V5 will be used as privacy to the NFS version 4 protocol. Kerberos V5 will be used as
skipping to change at page 20, line 7 skipping to change at page 20, line 5
| component4 | typedef utf8val_RECOMMENDED4 component4; | | component4 | typedef utf8val_RECOMMENDED4 component4; |
| | Represents path name components. | | | Represents path name components. |
| linktext4 | typedef utf8val_RECOMMENDED4 linktext4; | | linktext4 | typedef utf8val_RECOMMENDED4 linktext4; |
| | Symbolic link contents. | | | Symbolic link contents. |
| pathname4 | typedef component4 pathname4<>; | | pathname4 | typedef component4 pathname4<>; |
| | Represents path name for fs_locations. | | | Represents path name for fs_locations. |
| nfs_lockid4 | typedef uint64_t nfs_lockid4; | | nfs_lockid4 | typedef uint64_t nfs_lockid4; |
| verifier4 | typedef opaque | | verifier4 | typedef opaque |
| | verifier4[NFS4_VERIFIER_SIZE]; | | | verifier4[NFS4_VERIFIER_SIZE]; |
| | Verifier used for various operations | | | Verifier used for various operations |
| | (COMMIT, CREATE, EXCHANGE_ID, OPEN, | | | (COMMIT, CREATE, OPEN, READDIR, WRITE) |
| | READDIR, WRITE) NFS4_VERIFIER_SIZE is | | | NFS4_VERIFIER_SIZE is defined as 8. |
| | defined as 8. |
+----------------------+--------------------------------------------+ +----------------------+--------------------------------------------+
End of Base Data Types End of Base Data Types
Table 1 Table 1
2.2. Structured Data Types 2.2. Structured Data Types
2.2.1. nfstime4 2.2.1. nfstime4
skipping to change at page 25, line 14 skipping to change at page 25, line 14
2.2.16. stateid4 2.2.16. stateid4
struct stateid4 { struct stateid4 {
uint32_t seqid; uint32_t seqid;
opaque other[12]; opaque other[12];
}; };
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 starting value of the seqid field is undefined. is read-only. The server is required to increment the seqid field
The server is required to increment the seqid field monotonically at monotonically at each transition of the stateid. This is important
each transition of the stateid. This is important since the client since the client will inspect the seqid in OPEN stateids to determine
will inspect the seqid in OPEN stateids to determine the order of the order of OPEN processing done by the server.
OPEN processing done by the server.
3. RPC and Security Flavor 3. RPC and Security Flavor
The NFSv4 protocol is a Remote Procedure Call (RPC) application that The NFSv4 protocol is a Remote Procedure Call (RPC) application that
uses RPC version 2 and the corresponding eXternal Data Representation uses RPC version 2 and the corresponding eXternal Data Representation
(XDR) as defined in [4] and [14]. The RPCSEC_GSS security flavor as (XDR) as defined in [4] and [14]. The RPCSEC_GSS security flavor as
defined in [5] MUST be implemented as the mechanism to deliver defined in [5] MUST be implemented as the mechanism to deliver
stronger security for the NFSv4 protocol. However, deployment of stronger security for the NFSv4 protocol. However, deployment of
RPCSEC_GSS is optional. RPCSEC_GSS is optional.
skipping to change at page 28, line 11 skipping to change at page 28, line 10
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
implementor. Because this NFS protocol includes a method to implementor. 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. since the security negotiation is done via the MOUNT protocol.
For a discussion of NFS' use of RPCSEC_GSS and Kerberos V5, please For a discussion of NFS' use of RPCSEC_GSS and Kerberos V5, please
see [20]. see [20].
Users and implementors are warned that 56 bit DES is no longer
considered state of the art in terms of resistance to brute force
attacks. Once a revision to [15] is available that adds support for
AES, implementors are urged to incorporate AES into their NFSv4 over
Kerberos V5 protocol stacks, and users are similarly urged to migrate
to the use of AES.
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 may have multiple points within its filesystem name space NFS server may have multiple points within its filesystem name space
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
may be configured such that each of these entry points may have may be configured such that each of these entry points may have
different or multiple security mechanisms in use. different or multiple security mechanisms in use.
skipping to change at page 29, line 34 skipping to change at page 29, line 28
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
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 a
Network Information System domain or a DNS domain. 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
skipping to change at page 38, line 27 skipping to change at page 38, line 23
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
objects as symbolic links and special files are not allowed to be objects as symbolic links and special files are not allowed to be
named attributes. Further, directories may not be created in a named attributes. Further, directories may not be created in a
named attribute directory, so no hierarchical structure of named named attribute directory, so no hierarchical structure of named
attributes for a single object is allowed. attributes for a single object is allowed.
o If OPENATTR is done on a named attribute directory or on a named o If OPENATTR is done on a named attribute directory or on a named
attribute, the server MUST return NFS4ERR_WRONG_TYPE. attribute, the server MUST return an error.
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
skipping to change at page 48, line 23 skipping to change at page 47, line 50
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 disc space used by The value in bytes that represents the amount of disc 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, e.g. files or directories for which a quota_used value is maintained,
"all files with a given owner", "all files with a given group owner". e.g., "all files with a given owner", "all files with a given group
etc. The server is at liberty to choose any of those sets when owner", etc. The server is at liberty to choose any of those sets
providing the content of the quota_used attribute, but should do so when providing the content of the quota_used attribute, but should do
in a repeatable way. The rule may be configured per file system or so in a repeatable way. The rule may be configured per file system
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, the value returned SHOULD NOT be attribute is not NF4BLK or NF4CHR, the value returned SHOULD NOT be
considered useful. considered useful.
5.8.2.28. Attribute 42: space_avail 5.8.2.28. Attribute 42: space_avail
skipping to change at page 71, line 42 skipping to change at page 71, line 12
requirements refer to this section. But note that the methods have requirements refer to this section. But note that the methods have
behaviors specified with "SHOULD". This is intentional, to avoid behaviors specified with "SHOULD". This is intentional, to avoid
invalidating existing implementations that compute the mode according invalidating existing implementations that compute the mode according
to the withdrawn POSIX ACL draft (1003.1e draft 17), rather than by to the withdrawn POSIX ACL draft (1003.1e draft 17), rather than by
actual permissions on owner, group, and other. 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 subject to change, When any of the nine low-order mode bits are changed because the mode
either because the mode attribute was set or because the attribute was set, and no ACL attribute is explicitly set, the acl
mode_set_masked attribute was set and the mask included one or more attribute must be modified in accordance with the updated value of
bits from the nine low-order mode bits, and no ACL attribute is those bits. This must happen even if the value of the low-order bits
explicitly set, the acl attribute must be modified in accordance with is the same after the mode is set as before.
the updated value of those bits. This must happen even if the value
of the low-order bits 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*, in Section 6.3.2 yields the low-order nine bits (MODE4_R*, MODE4_W*,
MODE4_X*) of the mode attribute as modified by the attribute change. MODE4_X*) of the mode attribute as modified by the attribute change.
The ACL attributes SHOULD also be modified such that: The ACL attributes SHOULD also be modified such that:
skipping to change at page 72, line 40 skipping to change at page 72, line 8
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 or mode_set_masked When setting the acl and not setting the mode attribute, the
attributes, the permission bits of the mode need to be derived from permission bits of the mode need to be derived from the ACL. In this
the ACL. In this case, the ACL attribute SHOULD be set as given. case, the ACL attribute SHOULD be set as given. The nine low-order
The nine low-order bits of the mode attribute (MODE4_R*, MODE4_W*, bits of the mode attribute (MODE4_R*, MODE4_W*, MODE4_X*) MUST be
MODE4_X*) MUST be modified to match the result of the method modified to match the result of the method Section 6.3.2. The three
Section 6.3.2. The three high-order bits of the mode (MODE4_SUID, high-order bits of the mode (MODE4_SUID, MODE4_SGID, MODE4_SVTX)
MODE4_SGID, MODE4_SVTX) SHOULD remain unchanged. 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 (includes use of either the mode attribute When setting both the mode and the acl attribute in the same
or the mode_set_masked attribute) 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 (or ACL. The mode-related attribute is set as given, then the ACL
mode_set_masked), then ACL. The mode-related attribute is set as attribute is set as given, possibly changing the final mode, as
given, then the ACL attribute is set as given, possibly changing the described above in Section 6.4.1.2.
final mode, as 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
ACL attributes. ACL attributes.
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
skipping to change at page 87, line 27 skipping to change at page 86, line 43
non-cooperating servers have assigned the same client ID by accident. non-cooperating servers have assigned the same client ID by accident.
In the case of migration, the servers involved in the migration of a In the case of migration, the servers involved in the migration of a
file system SHOULD transfer all server state from the original to the file system SHOULD transfer all server state from the original to the
new server. When this is done, it must be done in a way that is new server. When this is done, it must be done in a way that is
transparent to the client. With replication, such a degree of common transparent to the client. With replication, such a degree of common
state is typically not the case. state is typically not the case.
This state transfer will reduce disruption to the client when a file This state transfer will reduce disruption to the client when a file
system transition occurs. If the servers are successful in system transition occurs. If the servers are successful in
transferring all state, the client can attempt to establish sessions transferring all state, then the client may use the existing stateids
associated with the client ID used for the source file system associated with that client ID for the old file system instance in
instance. If the server accepts that as a valid client ID, then the connection with that same client ID in connection with the
client may use the existing stateids associated with that client ID transitioned file system instance.
for the old file system instance in connection with that same client
ID in connection with the transitioned file system instance.
File systems cooperating in state management may actually share state File systems cooperating in state management may actually share state
or simply divide the identifier space so as to recognize (and reject or simply divide the identifier space so as to recognize (and reject
as stale) each other's stateids and client IDs. Servers that do as stale) each other's stateids and client IDs. Servers that do
share state may not do so under all conditions or at all times. If share state may not do so under all conditions or at all times. If
the server cannot be sure when accepting a client ID that it reflects the server cannot be sure when accepting a client ID that it reflects
the locks the client was given, the server must treat all associated the locks the client was given, the server must treat all associated
state as stale and report it as such to the client. state as stale and report it as such to the client.
The client must establish a new client ID on the destination, if it The client must establish a new client ID on the destination, if it
skipping to change at page 88, line 19 skipping to change at page 87, line 31
In the case of lock reclamation for a given file system after a file In the case of lock reclamation for a given file system after a file
system transition, edge conditions can arise similar to those for system transition, edge conditions can arise similar to those for
reclaim after server restart (although in the case of the planned reclaim after server restart (although in the case of the planned
state transfer associated with migration, these can be avoided by state transfer associated with migration, these can be avoided by
securely recording lock state as part of state migration). Unless securely recording lock state as part of state migration). Unless
the destination server can guarantee that locks will not be the destination server can guarantee that locks will not be
incorrectly granted, the destination server should not allow lock incorrectly granted, the destination server should not allow lock
reclaims and should avoid establishing a grace period. (See reclaims and should avoid establishing a grace period. (See
Section 9.14 for further details.) Section 9.14 for further details.)
Information about client identity may be propagated between servers
in the form of client_owner4 and associated verifiers, under the
assumption that the client presents the same values to all the
servers with which it deals.
Servers are encouraged to provide facilities to allow locks to be Servers are encouraged to provide facilities to allow locks to be
reclaimed on the new server after a file system transition. Often reclaimed on the new server after a file system transition. Often
such facilities may not be available and client should be prepared to such facilities may not be available and client should be prepared to
re-obtain locks, even though it is possible that the client may have re-obtain locks, even though it is possible that the client may have
its LOCK or OPEN request denied due to a conflicting lock. its LOCK or OPEN request denied due to a conflicting lock.
The consequences of having no facilities available to reclaim locks The consequences of having no facilities available to reclaim locks
on the new server will depend on the type of environment. In some on the new server will depend on the type of environment. In some
environments, such as the transition between read-only file systems, environments, such as the transition between read-only file systems,
such denial of locks should not pose large difficulties in practice. such denial of locks should not pose large difficulties in practice.
skipping to change at page 109, line 48 skipping to change at page 108, line 51
associated state-owner or state-owners (in the case of an open-owner/ associated state-owner or state-owners (in the case of an open-owner/
lock-owner pair) and the associated filehandle. When stateids are lock-owner pair) and the associated filehandle. When stateids are
used, the current filehandle must be the one associated with that used, the current filehandle must be the one associated with that
stateid. stateid.
All stateids associated with a given client ID are associated with a All stateids associated with a given client ID are associated with a
common lease that represents the claim of those stateids and the common lease that represents the claim of those stateids and the
objects they represent to be maintained by the server. See objects they represent to be maintained by the server. See
Section 9.5 for a discussion of the lease. Section 9.5 for a discussion of the lease.
The server may assign stateids independently for different clients. Each stateid must be unique to the server. Many operations take a
A stateid with the same bit pattern for one client may designate an stateid as an argument but not a clientid, so the server must be able
entirely different set of locks for a different client. The stateid to infer the client from the stateid.
is always interpreted with respect to the client ID associated with
the current session.
9.1.3.1. Stateid Types 9.1.3.1. Stateid Types
With the exception of special stateids (see Section 9.1.3.3), each With the exception of special stateids (see Section 9.1.3.3), each
stateid represents locking objects of one of a set of types defined stateid represents locking objects of one of a set of types defined
by the NFSv4 protocol. Note that in all these cases, where we speak by the NFSv4 protocol. Note that in all these cases, where we speak
of guarantee, it is understood there are situations such as a client of guarantee, it is understood there are situations such as a client
restart, or lock revocation, that allow the guarantee to be voided. restart, or lock revocation, that allow the guarantee to be voided.
o Stateids may represent opens of files. o Stateids may represent opens of files.
skipping to change at page 110, line 43 skipping to change at page 109, line 44
A stateid represents a single delegation held by a client for a A stateid represents a single delegation held by a client for a
particular filehandle. particular filehandle.
9.1.3.2. Stateid Structure 9.1.3.2. Stateid Structure
Stateids are divided into two fields, a 96-bit "other" field Stateids are divided into two fields, a 96-bit "other" field
identifying the specific set of locks and a 32-bit "seqid" sequence identifying the specific set of locks and a 32-bit "seqid" sequence
value. Except in the case of special stateids (see Section 9.1.3.3), value. Except in the case of special stateids (see Section 9.1.3.3),
a particular value of the "other" field denotes a set of locks of the a particular value of the "other" field denotes a set of locks of the
same type (for example, byte-range locks, opens, delegations, or same type (for example, byte-range locks, opens, or delegations), for
layouts), for a specific file or directory, and sharing the same a specific file or directory, and sharing the same ownership
ownership characteristics. The seqid designates a specific instance characteristics. The seqid designates a specific instance of such a
of such a set of locks, and is incremented to indicate changes in set of locks, and is incremented to indicate changes in such a set of
such a set of locks, either by the addition or deletion of locks from locks, either by the addition or deletion of locks from the set, a
the set, a change in the byte-range they apply to, or an upgrade or change in the byte-range they apply to, or an upgrade or downgrade in
downgrade in the type of one or more locks. the type of one or more locks.
When such a set of locks is first created, the server returns a When such a set of locks is first created, the server SHOULD return a
stateid with seqid value of one. On subsequent operations that stateid with seqid value of one. On subsequent operations that
modify the set of locks, the server is required to increment the modify the set of locks, the server is required to increment the
"seqid" field by one whenever it returns a stateid for the same "seqid" field by one whenever it returns a stateid for the same
state-owner/file/type combination and there is some change in the set state-owner/file/type combination and there is some change in the set
of locks actually designated. In this case, the server will return a of locks actually designated. In this case, the server will return a
stateid with an "other" field the same as previously used for that stateid with an "other" field the same as previously used for that
state-owner/file/type combination, with an incremented "seqid" field. state-owner/file/type combination, with an incremented "seqid" field.
This pattern continues until the seqid is incremented past This pattern continues until the seqid is incremented past
NFS4_UINT32_MAX, and one (not zero) is the next seqid value. The NFS4_UINT32_MAX, and one (not zero) SHOULD be the next seqid value.
purpose of the incrementing of the seqid is to allow the server to The purpose of the incrementing of the seqid is to allow the server
communicate to the client the order in which operations that modified to communicate to the client the order in which operations that
locking state associated with a stateid have been processed and to modified locking state associated with a stateid have been processed.
make it possible for the client to send requests that are conditional
on the set of locks not having changed since the stateid in question
was returned.
When a client sends a stateid to the server, it has two choices with
regard to the seqid sent. It may set the seqid to zero to indicate
to the server that it wishes the most up-to-date seqid for that
stateid's "other" field to be used. This would be the common choice
in the case of a stateid sent with a READ or WRITE operation. It
also may set a non-zero value, in which case the server checks if
that seqid is the correct one. In that case, the server is required
to return NFS4ERR_OLD_STATEID if the seqid is lower than the most
current value and NFS4ERR_BAD_STATEID if the seqid is greater than
the most current value. This would be the common choice in the case
of stateids sent with a CLOSE or OPEN_DOWNGRADE. Because OPENs may
be sent in parallel for the same owner, a client might close a file
without knowing that an OPEN upgrade had been done by the server,
changing the lock in question. If CLOSE were sent with a zero seqid,
the OPEN upgrade would be canceled before the client even received an
indication that an upgrade had happened.
When a stateid is sent by the server to the client as part of a
callback operation, it is not subject to checking for a current seqid
and returning NFS4ERR_OLD_STATEID. This is because the client is not
in a position to know the most up-to-date seqid and thus cannot
verify it. Unless specially noted, the seqid value for a stateid
sent by the server to the client as part of a callback is required to
be zero with NFS4ERR_BAD_STATEID returned if it is not.
In making comparisons between seqids, both by the client in In making comparisons between seqids, both by the client in
determining the order of operations and by the server in determining determining the order of operations and by the server in determining
whether the NFS4ERR_OLD_STATEID is to be returned, the possibility of whether the NFS4ERR_OLD_STATEID is to be returned, the possibility of
the seqid being swapped around past the NFS4_UINT32_MAX value needs the seqid being swapped around past the NFS4_UINT32_MAX value needs
to be taken into account. to be taken into account.
9.1.3.3. Special Stateids 9.1.3.3. Special Stateids
Stateid values whose "other" field is either all zeros or all ones Stateid values whose "other" field is either all zeros or all ones
skipping to change at page 112, line 29 skipping to change at page 110, line 49
associated with the request. When an anonymous stateid value is associated with the request. When an anonymous stateid value is
used, and an existing open denies the form of access requested, used, and an existing open denies the form of access requested,
then access will be denied to the request. then access will be denied to the request.
o When "other" and "seqid" are both all ones, the stateid is a o When "other" and "seqid" are both all ones, the stateid is a
special READ bypass stateid. When this value is used in WRITE or special READ bypass stateid. When this value is used in WRITE or
SETATTR, it is treated like the anonymous value. When used in SETATTR, it is treated like the anonymous value. When used in
READ, the server MAY grant access, even if access would normally READ, the server MAY grant access, even if access would normally
be denied to READ requests. be denied to READ requests.
o When "other" is zero and "seqid" is one, the stateid represents
the current stateid, which is whatever value is the last stateid
returned by an operation within the COMPOUND. In the case of an
OPEN, the stateid returned for the open file, and not the
delegation is used. The stateid passed to the operation in place
of the special value has its "seqid" value set to zero, except
when the current stateid is used by the operation CLOSE or
OPEN_DOWNGRADE. If there is no operation in the COMPOUND which
has returned a stateid value, the server MUST return the error
NFS4ERR_BAD_STATEID. As illustrated in Figure 5, if the value of
a current stateid is a special stateid, and the stateid of an
operation's arguments has "other" set to zero, and "seqid" set to
one, then the server MUST return the error NFS4ERR_BAD_STATEID.
o When "other" is zero and "seqid" is NFS4_UINT32_MAX, the stateid
represents a reserved stateid value defined to be invalid. When
this stateid is used, the server MUST return the error
NFS4ERR_BAD_STATEID.
If a stateid value is used which has all zero or all ones in the If a stateid value is used which has all zero or all ones in the
"other" field, but does not match one of the cases above, the server "other" field, but does not match one of the cases above, the server
MUST return the error NFS4ERR_BAD_STATEID. MUST return the error NFS4ERR_BAD_STATEID.
Special stateids, unlike other stateids, are not associated with Special stateids, unlike other stateids, are not associated with
individual client IDs or filehandles and can be used with all valid individual client IDs or filehandles and can be used with all valid
client IDs and filehandles. In the case of a special stateid client IDs and filehandles.
designating the current stateid, the current stateid value
substituted for the special stateid is associated with a particular
client ID and filehandle, and so, if it is used where current
filehandle does not match that associated with the current stateid,
the operation to which the stateid is passed will return
NFS4ERR_BAD_STATEID.
9.1.3.4. Stateid Lifetime and Validation 9.1.3.4. Stateid Lifetime and Validation
Stateids must remain valid until either a client restart or a server Stateids must remain valid until either a client restart or a server
restart or until the client returns all of the locks associated with restart or until the client returns all of the locks associated with
the stateid by means of an operation such as CLOSE or DELEGRETURN. the stateid by means of an operation such as CLOSE or DELEGRETURN.
If the locks are lost due to revocation as long as the client ID is If the locks are lost due to revocation as long as the client ID is
valid, the stateid remains a valid designation of that revoked state. valid, the stateid remains a valid designation of that revoked state.
Stateids associated with byte-range locks are an exception. They Stateids associated with byte-range locks are an exception. They
remain valid even if a LOCKU frees all remaining locks, so long as remain valid even if a LOCKU frees all remaining locks, so long as
skipping to change at page 114, line 31 skipping to change at page 112, line 26
When a stateid is being tested, and the "other" field is all zeros or When a stateid is being tested, and the "other" field is all zeros or
all ones, a check that the "other" and "seqid" fields match a defined all ones, a check that the "other" and "seqid" fields match a defined
combination for a special stateid is done and the results determined combination for a special stateid is done and the results determined
as follows: as follows:
o If the "other" and "seqid" fields do not match a defined o If the "other" and "seqid" fields do not match a defined
combination associated with a special stateid, the error combination associated with a special stateid, the error
NFS4ERR_BAD_STATEID is returned. NFS4ERR_BAD_STATEID is returned.
o If the special stateid is one designating the current stateid, and
there is a current stateid, then the current stateid is
substituted for the special stateid and the checks appropriate to
non-special stateids in performed.
o If the combination is valid in general but is not appropriate to o If the combination is valid in general but is not appropriate to
the context in which the stateid is used (e.g. an all-zero stateid the context in which the stateid is used (e.g., an all-zero
is used when an open stateid is required in a LOCK operation), the stateid is used when an open stateid is required in a LOCK
error NFS4ERR_BAD_STATEID is also returned. operation), the error NFS4ERR_BAD_STATEID is also returned.
o Otherwise, the check is completed and the special stateid is o Otherwise, the check is completed and the special stateid is
accepted as valid. accepted as valid.
When a stateid is being tested, and the "other" field is neither all When a stateid is being tested, and the "other" field is neither all
zeros or all ones, the following procedure could be used to validate zeros or all ones, the following procedure could be used to validate
an incoming stateid and return an appropriate error, when necessary, an incoming stateid and return an appropriate error, when necessary,
assuming that the "other" field would be divided into a table index assuming that the "other" field would be divided into a table index
and an entry generation. and an entry generation.
o If the table index field is outside the range of the associated o If the table index field is outside the range of the associated
table, return NFS4ERR_BAD_STATEID. table, return NFS4ERR_BAD_STATEID.
o If the selected table entry is of a different generation than that o If the selected table entry is of a different generation than that
specified in the incoming stateid, return NFS4ERR_BAD_STATEID. specified in the incoming stateid, return NFS4ERR_BAD_STATEID.
o If the selected table entry does not match the current filehandle, o If the selected table entry does not match the current filehandle,
return NFS4ERR_BAD_STATEID. return NFS4ERR_BAD_STATEID.
o If the client ID in the table entry does not match the client ID
associated with the current session, return NFS4ERR_BAD_STATEID.
o If the stateid represents revoked state, then return o If the stateid represents revoked state, then return
NFS4ERR_EXPIRED, NFS4ERR_ADMIN_REVOKED, or NFS4ERR_DELEG_REVOKED, NFS4ERR_EXPIRED or NFS4ERR_ADMIN_REVOKED, as appropriate.
as appropriate.
o If the stateid type is not valid for the context in which the o If the stateid type is not valid for the context in which the
stateid appears, return NFS4ERR_BAD_STATEID. Note that a stateid stateid appears, return NFS4ERR_BAD_STATEID. Note that a stateid
may be valid in general, but be invalid for a particular may be valid in general, but be invalid for a particular
operation, as, for example, when a stateid which doesn't represent operation, as, for example, when a stateid which doesn't represent
byte-range locks is passed to the non-from_open case of LOCK or to byte-range locks is passed to the non-from_open case of LOCK or to
LOCKU, or when a stateid which does not represent an open is LOCKU, or when a stateid which does not represent an open is
passed to CLOSE or OPEN_DOWNGRADE. In such cases, the server MUST passed to CLOSE or OPEN_DOWNGRADE. In such cases, the server MUST
return NFS4ERR_BAD_STATEID. return NFS4ERR_BAD_STATEID.
o If the "seqid" field is not zero, and it is greater than the o If the "seqid" field is not zero, and it is greater than the
current sequence value corresponding the current "other" field, current sequence value corresponding the current "other" field,
return NFS4ERR_BAD_STATEID. return NFS4ERR_BAD_STATEID.
o If the "seqid" field is not zero, and it is less than the current o If the "seqid" field is less than the current sequence value
sequence value corresponding the current "other" field, return corresponding the current "other" field, return
NFS4ERR_OLD_STATEID. NFS4ERR_OLD_STATEID.
o Otherwise, the stateid is valid and the table entry should contain o Otherwise, the stateid is valid and the table entry should contain
any additional information about the type of stateid and any additional information about the type of stateid and
information associated with that particular type of stateid, such information associated with that particular type of stateid, such
as the associated set of locks, such as open-owner and lock-owner as the associated set of locks, such as open-owner and lock-owner
information, as well as information on the specific locks, such as information, as well as information on the specific locks, such as
open modes and byte ranges. open modes and byte ranges.
9.1.3.5. Stateid Use for I/O Operations 9.1.3.5. Stateid Use for I/O Operations
skipping to change at page 120, line 49 skipping to change at page 118, line 36
closed files with locks outstanding. closed files with locks outstanding.
LOCK, LOCKU, OPEN, OPEN_DOWNGRADE, and CLOSE each contain a sequence LOCK, LOCKU, OPEN, OPEN_DOWNGRADE, and CLOSE each contain a sequence
number and therefore the risk of the replay of these operations number and therefore the risk of the replay of these operations
resulting in undesired effects is non-existent while the server resulting in undesired effects is non-existent while the server
maintains the state-owner state. maintains the state-owner state.
9.1.8. Interactions of multiple sequence values 9.1.8. Interactions of multiple sequence values
Some Operations may have multiple sources of data for request Some Operations may have multiple sources of data for request
sequence checking and retrannsmision determination. Some Operations sequence checking and retransmission determination. Some Operations
have multiple sequence values associated with multiple types of have multiple sequence values associated with multiple types of
state-owners. In addition, such Operations may also have a stateid state-owners. In addition, such Operations may also have a stateid
with its own seqid value, that will be checked for validity. with its own seqid value, that will be checked for validity.
As noted above, there may be multiple sequence values to check The As noted above, there may be multiple sequence values to check. The
following rules should be followed by the server in processing these following rules should be followed by the server in processing these
multiple sequence values within a single operation. multiple sequence values within a single operation.
o When a sequence value associated with a state-owner is unavailable o When a sequence value associated with a state-owner is unavailable
for checking because the state-owner is unknown to the server, it for checking because the state-owner is unknown to the server, it
take no part in the comparison. Similarly, when the stateid seqid takes no part in the comparison.
is given as zero, the stateid seqid takes no part in the checking.
o When any of the state-owner sequence values are invalid, o When any of the state-owner sequence values are invalid,
NFS4ERR_BADSEQ is returned. When a stateid sequence is checked, NFS4ERR_BADSEQ is returned. When a stateid sequence is checked,
NFSS4ERR_BAD_STATEID, or NFS4ERR_OLDSTATEID is returned as NFS4ERR_BAD_STATEID, or NFS4ERR_OLDSTATEID is returned as
appropriate, but NFS4ERR_BADSEQ has priority. appropriate, but NFS4ERR_BADSEQ has priority.
o When any one of the sequence values matches a previous request, o When any one of the sequence values matches a previous request,
for a state-owner, it is treated a retransmission and not re- for a state-owner, it is treated as a retransmission and not re-
executed. When the type of the operation doe not match that executed. When the type of the operation does not match that
originally used, NFS4ERR_BADSEQ is returned. When the server can originally used, NFS4ERR_BADSEQ is returned. When the server can
determine that the request differs from the original it may return determine that the request differs from the original it may return
NFS4ERR_BADSEQ. NFS4ERR_BADSEQ.
o When multiple of the sequence values match previous operations, o When multiple of the sequence values match previous operations,
but the operations are not the same, NFS4ERR_BADSEQ is returned. but the operations are not the same, NFS4ERR_BADSEQ is returned.
o When there are no available sequence values available for o When there are no available sequence values available for
comparison and the operation is an OPEN, the server indicates to comparison and the operation is an OPEN, the server indicates to
the client that an OPEN_CONFRIM is required, unless it can the client that an OPEN_CONFIRM is required, unless it can
conclusively determine that confirmation is not required (e.g., by conclusively determine that confirmation is not required (e.g., by
knowing that no open-owner state has ever been released for the knowing that no open-owner state has ever been released for the
current clientid). current clientid).
For other operations, lack of available sequence values for
checking can only result from specification of a stateid with a
sequence value of zero.
Because specification of stateids with a sequence value of zero can
result in no sequence checking under certain conditions, clients
should avoid using them in connection with operations in which state-
owners are used together with state-owner sequence values.
9.1.9. Releasing state-owner State 9.1.9. Releasing state-owner State
When a particular state-owner no longer holds open or file locking When a particular state-owner no longer holds open or file locking
state at the server, the server may choose to release the sequence state at the server, the server may choose to release the sequence
number state associated with the state-owner. The server may make number state associated with the state-owner. The server may make
this choice based on lease expiration, for the reclamation of server this choice based on lease expiration, for the reclamation of server
memory, or other implementation specific details. Note that when memory, or other implementation specific details. Note that when
this is done, a retransmitted request, normally identified by a this is done, a retransmitted request, normally identified by a
matching state-owner sequence may not be correctly recognized, so matching state-owner sequence may not be correctly recognized, so
that the client will not receive the original response that it would that the client will not receive the original response that it would
skipping to change at page 154, line 23 skipping to change at page 151, line 50
o The probability of future conflicting open requests should be low o The probability of future conflicting open requests should be low
based on the recent history of the file. based on the recent history of the file.
o The existence of any server-specific semantics of OPEN/CLOSE that o The existence of any server-specific semantics of OPEN/CLOSE that
would make the required handling incompatible with the prescribed would make the required handling incompatible with the prescribed
handling that the delegated client would apply (see below). handling that the delegated client would apply (see below).
There are two types of open delegations, OPEN_DELEGATE_READ and There are two types of open delegations, OPEN_DELEGATE_READ and
OPEN_DELEGATE_WRITE. A OPEN_DELEGATE_READ delegation allows a client OPEN_DELEGATE_WRITE. A OPEN_DELEGATE_READ delegation allows a client
to handle, on its own, requests to open a file for reading that do to handle, on its own, requests to open a file for reading that do
not deny read access to others. Multiple OPEN_DELEGATE_READ not deny read access to others. It MUST, however, continue to send
delegations may be outstanding simultaneously and do not conflict. A all requests to open a file for writing to the server. Multiple
OPEN_DELEGATE_WRITE delegation allows the client to handle, on its OPEN_DELEGATE_READ delegations may be outstanding simultaneously and
own, all opens. Only one OPEN_DELEGATE_WRITE delegation may exist do not conflict. A OPEN_DELEGATE_WRITE delegation allows the client
for a given file at a given time and it is inconsistent with any to handle, on its own, all opens. Only one OPEN_DELEGATE_WRITE
OPEN_DELEGATE_READ delegations. delegation may exist for a given file at a given time and it is
inconsistent with any OPEN_DELEGATE_READ delegations.
When a client has a OPEN_DELEGATE_READ delegation, it may not make When a single client holds a OPEN_DELEGATE_READ delegation, it is
any changes to the contents or attributes of the file but it is assured that no other client may modify the contents or attributes of
assured that no other client may do so. When a client has a the file. If more than one client holds an OPEN_DELEGATE_READ
OPEN_DELEGATE_WRITE delegation, it may modify the file data since no delegation, then the contents and attributes of that file are not
other client will be accessing the file's data. The client holding a allowed to change. When a client has an OPEN_DELEGATE_WRITE
OPEN_DELEGATE_WRITE delegation may only affect file attributes which delegation, it may modify the file data since no other client will be
are intimately connected with the file data: size, time_modify, accessing the file's data. The client holding a OPEN_DELEGATE_WRITE
change. delegation may only affect file attributes which are intimately
connected with the file data: size, time_modify, change.
When a client has an open delegation, it does not send OPENs or When a client has an open delegation, it does not send OPENs or
CLOSEs to the server but updates the appropriate status internally. CLOSEs to the server but updates the appropriate status internally.
For a OPEN_DELEGATE_READ delegation, opens that cannot be handled For a OPEN_DELEGATE_READ delegation, opens that cannot be handled
locally (opens for write or that deny read access) must be sent to locally (opens for write or that deny read access) must be sent to
the server. the server.
When an open delegation is made, the response to the OPEN contains an When an open delegation is made, the response to the OPEN contains an
open delegation structure which specifies the following: open delegation structure which specifies the following:
skipping to change at page 156, line 10 skipping to change at page 153, line 39
each user by use of the ACCESS operation. This should be the case each user by use of the ACCESS operation. This should be the case
even if an ACCESS operation would not be required otherwise. As even if an ACCESS operation would not be required otherwise. As
mentioned before, the server may enforce frequent authentication by mentioned before, the server may enforce frequent authentication by
returning an nfsace4 denying all access with every open delegation. returning an nfsace4 denying all access with every open delegation.
10.4.1. Open Delegation and Data Caching 10.4.1. Open Delegation and Data Caching
OPEN delegation allows much of the message overhead associated with OPEN delegation allows much of the message overhead associated with
the opening and closing files to be eliminated. An open when an open the opening and closing files to be eliminated. An open when an open
delegation is in effect does not require that a validation message be delegation is in effect does not require that a validation message be
sent to the server. The continued endurance of the sent to the server unless there exists a potential for conflict with
the requested share mode. The continued endurance of the
"OPEN_DELEGATE_READ delegation" provides a guarantee that no OPEN for "OPEN_DELEGATE_READ delegation" provides a guarantee that no OPEN for
write and thus no write has occurred. Similarly, when closing a file write and thus no write has occurred that did not originate from this
opened for write and if OPEN_DELEGATE_WRITE delegation is in effect, client. Similarly, when closing a file opened for write and if
the data written does not have to be flushed to the server until the OPEN_DELEGATE_WRITE delegation is in effect, the data written does
open delegation is recalled. The continued endurance of the open not have to be flushed to the server until the open delegation is
delegation provides a guarantee that no open and thus no read or recalled. The continued endurance of the open delegation provides a
write has been done by another client. guarantee that no open and thus no read or write has been done by
another client.
For the purposes of open delegation, READs and WRITEs done without an For the purposes of open delegation, READs and WRITEs done without an
OPEN are treated as the functional equivalents of a corresponding OPEN are treated as the functional equivalents of a corresponding
type of OPEN. This refers to the READs and WRITEs that use the type of OPEN. This refers to the READs and WRITEs that use the
special stateids consisting of all zero bits or all one bits. special stateids consisting of all zero bits or all one bits.
Therefore, READs or WRITEs with a special stateid done by another Therefore, READs or WRITEs with a special stateid done by another
client will force the server to recall a OPEN_DELEGATE_WRITE client will force the server to recall a OPEN_DELEGATE_WRITE
delegation. A WRITE with a special stateid done by another client delegation. A WRITE with a special stateid done by another client
will force a recall of OPEN_DELEGATE_READ delegations. will force a recall of OPEN_DELEGATE_READ delegations.
skipping to change at page 175, line 12 skipping to change at page 173, line 9
remote file access protocols will be as well. It is generally a remote file access protocols will be as well. It is generally a
functional requirement in practice for the users of the NFSv4 functional requirement in practice for the users of the NFSv4
protocol (although it may be formally out of scope for this document) protocol (although it may be formally out of scope for this document)
for the implementation to allow files created by other protocols and for the implementation to allow files created by other protocols and
by local operations on the file system to be accessed using NFS by local operations on the file system to be accessed using NFS
version 4 as well. version 4 as well.
It also needs to be understood that a considerable portion of file It also needs to be understood that a considerable portion of file
name processing will occur within the implementation of the file name processing will occur within the implementation of the file
system rather than within the limits of the NFSv4 server system rather than within the limits of the NFSv4 server
implementation per se. As a result, cetain aspects of name implementation per se. As a result, certain aspects of name
processing may change as the locus of processing moves from file processing may change as the locus of processing moves from file
system to file system. As a result of these factors, the protocol system to file system. As a result of these factors, the protocol
cannot enforce uniformity of name-related processing upon NFSv4 cannot enforce uniformity of name-related processing upon NFSv4
server requests on the server as a whole. Because the server server requests on the server as a whole. Because the server
interacts with existing file system implementations, the same server interacts with existing file system implementations, the same server
handling will produce different behavior when interacting with handling will produce different behavior when interacting with
different file system implementations. To attempt to require uniform different file system implementations. To attempt to require uniform
behavior, and treat the the protocol server and the file system as a behavior, and treat the the protocol server and the file system as a
unified application, would considerably limit the usefulness of the unified application, would considerably limit the usefulness of the
protocol. protocol.
skipping to change at page 181, line 13 skipping to change at page 179, line 13
particular bits such as the high-order bit to zero MUST NOT be done. particular bits such as the high-order bit to zero MUST NOT be done.
12.2.3. Individual Types and Their Handling 12.2.3. Individual Types and Their Handling
The first table outlines the handling for the primary string types, The first table outlines the handling for the primary string types,
i.e., those not derived as a prefix or a suffix from a mixture type. i.e., those not derived as a prefix or a suffix from a mixture type.
+-----------------+----------+-------+------------------------------+ +-----------------+----------+-------+------------------------------+
| Type | Parent | Class | Explanation | | Type | Parent | Class | Explanation |
+-----------------+----------+-------+------------------------------+ +-----------------+----------+-------+------------------------------+
| comptag4 | USHOULD | NIP | Tag expected to be UTF-8but | | comptag4 | USHOULD | NIP | Tag expected to be UTF-8 but |
| | | | no validation by server or | | | | | no validation by server or |
| | | | client is to be done. | | | | | client is to be done. |
| component4 | UVSHOULD | NFS | Should be utf8 but clients | | component4 | UVSHOULD | NFS | Should be utf8 but clients |
| | | | may need to access file | | | | | may need to access file |
| | | | systems with a different | | | | | systems with a different |
| | | | name structure, such as file | | | | | name structure, such as file |
| | | | systems that have non-utf8 | | | | | systems that have non-utf8 |
| | | | names. | | | | | names. |
| linktext4 | UVSHOULD | NFS | Should be utf8 since text | | linktext4 | UVSHOULD | NFS | Should be utf8 since text |
| | | | may include name components. | | | | | may include name components. |
skipping to change at page 204, line 23 skipping to change at page 202, line 23
accounting purposes), and where cross-connection between the accounting purposes), and where cross-connection between the
regions are not allowed. regions are not allowed.
13.1.5. State Management Errors 13.1.5. State Management Errors
These errors indicate problems with the stateid (or one of the These errors indicate problems with the stateid (or one of the
stateids) passed to a given operation. This includes situations in stateids) passed to a given operation. This includes situations in
which the stateid is invalid as well as situations in which the which the stateid is invalid as well as situations in which the
stateid is valid but designates revoked locking state. Depending on stateid is valid but designates revoked locking state. Depending on
the operation, the stateid when valid may designate opens, byte-range the operation, the stateid when valid may designate opens, byte-range
locks, file delegations, layouts, or device maps. locks, or file delegations.
13.1.5.1. NFS4ERR_ADMIN_REVOKED (Error Code 10047) 13.1.5.1. NFS4ERR_ADMIN_REVOKED (Error Code 10047)
A stateid designates locking state of any type that has been revoked A stateid designates locking state of any type that has been revoked
due to administrative interaction, possibly while the lease is valid. due to administrative interaction, possibly while the lease is valid.
13.1.5.2. NFS4ERR_BAD_STATEID (Error Code 10026) 13.1.5.2. NFS4ERR_BAD_STATEID (Error Code 10026)
A stateid generated by the current server instance, but which does A stateid generated by the current server instance, but which does
not designate any locking state (either current or superseded) for a not designate any locking state (either current or superseded) for a
skipping to change at page 204, line 50 skipping to change at page 202, line 50
lease expiration, or following a later request for a conflicting lease expiration, or following a later request for a conflicting
lock. lock.
13.1.5.4. NFS4ERR_LEASE_MOVED (Error Code 10031) 13.1.5.4. NFS4ERR_LEASE_MOVED (Error Code 10031)
A lease being renewed is associated with a file system that has been A lease being renewed is associated with a file system that has been
migrated to a new server. migrated to a new server.
13.1.5.5. NFS4ERR_OLD_STATEID (Error Code 10024) 13.1.5.5. NFS4ERR_OLD_STATEID (Error Code 10024)
A stateid with a non-zero seqid value does match the current seqid A stateid is provided with a seqid value that is not the most
for the state designated by the user. current.
13.1.5.6. NFS4ERR_STALE_STATEID (Error Code 10023) 13.1.5.6. NFS4ERR_STALE_STATEID (Error Code 10023)
A stateid generated by an earlier server instance was used. A stateid generated by an earlier server instance was used.
13.1.6. Security Errors 13.1.6. Security Errors
These are the various permission-related errors in NFSv4. These are the various permission-related errors in NFSv4.
13.1.6.1. NFS4ERR_ACCESS (Error Code 13) 13.1.6.1. NFS4ERR_ACCESS (Error Code 13)
skipping to change at page 227, line 22 skipping to change at page 225, line 22
While the current filehandle is set as the result of operations like While the current filehandle is set as the result of operations like
LOOKUP, the saved filehandle must be set directly with the use of the LOOKUP, the saved filehandle must be set directly with the use of the
SAVEFH operation. The SAVEFH operations copies the current SAVEFH operation. The SAVEFH operations copies the current
filehandle value to the saved value. The saved filehandle value is filehandle value to the saved value. The saved filehandle value is
used in combination with the current filehandle value for the LINK used in combination with the current filehandle value for the LINK
and RENAME operations. The RESTOREFH operation will copy the saved and RENAME operations. The RESTOREFH operation will copy the saved
filehandle value to the current filehandle value; as a result, the filehandle value to the current filehandle value; as a result, the
saved filehandle value may be used a sort of "scratch" area for the saved filehandle value may be used a sort of "scratch" area for the
client's series of operations. client's series of operations.
15.2.4.2. Current Stateid
The COMPOUND processing environment also have a current stateid and a
saved stateid, which allows for the passing of stateids between
operations.
A "current stateid" is the stateid that is associated with the
current filehandle. The current stateid may only be changed by an
operation that modifies the current filehandle or returns a stateid.
If an operation returns a stateid it MUST set the current stateid to
the returned value. If an operation sets the current filehandle but
does not return a stateid, the current stateid MUST be set to the
all-zeros special stateid, i.e. (seqid, other) = (0, 0). If an
operation uses a stateid as an argument but does not return a
stateid, the current stateid MUST NOT be changed. E.g., PUTFH,
PUTROOTFH, and PUTPUBFH will change the current server state from
{ocfh, (osid)} to {cfh, (0, 0)} while LOCK will change the current
state from {cfh, (osid} to {cfh, (nsid)}. Operations like LOOKUP
that transform a current filehandle and component name into a new
current filehandle will also change the current stateid to {0, 0}.
The SAVEFH and RESTOREFH operations will save and restore both the
current filehandle and the current stateid as a set.
The following example is the common case of a simple READ operation
with a supplied stateid showing that the PUTFH initializes the
current stateid to (0, 0). The subsequent READ with stateid (sid1)
leaves the current stateid unchanged, but does evaluate the the
operation.
PUTFH fh1 - -> {fh1, (0, 0)}
READ (sid1), 0, 1024 {fh1, (0, 0)} -> {fh1, (0, 0)}
Figure 2
This next example performs an OPEN with the root filehandle and as a
result generates stateid (sid1). The next operation specifies the
READ with the argument stateid set such that (seqid, other) are equal
to (1, 0), but the current stateid set by the previous operation is
actually used when the operation is evaluated. This allows correct
interaction with any existing, potentially conflicting, locks.
PUTROOTFH - -> {fh1, (0, 0)}
OPEN "compA" {fh1, (0, 0)} -> {fh2, (sid1)}
READ (1, 0), 0, 1024 {fh2, (sid1)} -> {fh2, (sid1)}
CLOSE (1, 0) {fh2, (sid1)} -> {fh2, (sid2)}
Figure 3
This next example is similar to the second in how it passes the
stateid sid2 generated by the LOCK operation to the next READ
operation. This allows the client to explicitly surround a single
I/O operation with a lock and its appropriate stateid to guarantee
correctness with other client locks. The example also shows how
SAVEFH and RESTOREFH can save and later re-use a filehandle and
stateid, passing them as the current filehandle and stateid to a READ
operation.
PUTFH fh1 - -> {fh1, (0, 0)}
LOCK 0, 1024, (sid1) {fh1, (sid1)} -> {fh1, (sid2)}
READ (1, 0), 0, 1024 {fh1, (sid2)} -> {fh1, (sid2)}
LOCKU 0, 1024, (1, 0) {fh1, (sid2)} -> {fh1, (sid3)}
SAVEFH {fh1, (sid3)} -> {fh1, (sid3)}
PUTFH fh2 {fh1, (sid3)} -> {fh2, (0, 0)}
WRITE (1, 0), 0, 1024 {fh2, (0, 0)} -> {fh2, (0, 0)}
RESTOREFH {fh2, (0, 0)} -> {fh1, (sid3)}
READ (1, 0), 1024, 1024 {fh1, (sid3)} -> {fh1, (sid3)}
Figure 4
The final example shows a disallowed use of the current stateid. The
client is attempting to implicitly pass anonymous special stateid,
(0,0) to the READ operation. The server MUST return
NFS4ERR_BAD_STATEID in the reply to the READ operation.
PUTFH fh1 - -> {fh1, (0, 0)}
READ (1, 0), 0, 1024 {fh1, (0, 0)} -> NFS4ERR_BAD_STATEID
Figure 5
15.2.5. IMPLEMENTATION 15.2.5. IMPLEMENTATION
Since an error of any type may occur after only a portion of the Since an error of any type may occur after only a portion of the
operations have been evaluated, the client must be prepared to operations have been evaluated, the client must be prepared to
recover from any failure. If the source of an NFS4ERR_RESOURCE error recover from any failure. If the source of an NFS4ERR_RESOURCE error
was a complex or lengthy set of operations, it is likely that if the was a complex or lengthy set of operations, it is likely that if the
number of operations were reduced the server would be able to number of operations were reduced the server would be able to
evaluate them successfully. Therefore, the client is responsible for evaluate them successfully. Therefore, the client is responsible for
dealing with this type of complexity in recovery. dealing with this type of complexity in recovery.
skipping to change at page 251, line 43 skipping to change at page 248, line 43
PUTFH (directory filehandle) PUTFH (directory filehandle)
LOOKUP "pub" LOOKUP "pub"
GETFH GETFH
LOOKUP "foo" LOOKUP "foo"
GETFH GETFH
LOOKUP "bar" LOOKUP "bar"
GETFH GETFH
NFSv4 servers depart from the semantics of previous NFS versions in NFSv4 servers depart from the semantics of previous NFS versions in
allowing LOOKUP requests to cross mountpoints on the server. The allowing LOOKUP requests to cross mount points on the server. The
client can detect a mountpoint crossing by comparing the fsid client can detect a mount point crossing by comparing the fsid
attribute of the directory with the fsid attribute of the directory attribute of the directory with the fsid attribute of the directory
looked up. If the fsids are different then the new directory is a looked up. If the fsids are different then the new directory is a
server mountpoint. UNIX clients that detect a mountpoint crossing server mount point. UNIX clients that detect a mount point crossing
will need to mount the server's filesystem. This needs to be done to will need to mount the server's filesystem. This needs to be done to
maintain the file object identity checking mechanisms common to UNIX maintain the file object identity checking mechanisms common to UNIX
clients. clients.
Servers that limit NFS access to "shares" or "exported" filesystems Servers that limit NFS access to "shares" or "exported" filesystems
should provide a pseudo-filesystem into which the exported should provide a pseudo-filesystem into which the exported
filesystems can be integrated, so that clients can browse the filesystems can be integrated, so that clients can browse the
server's name space. The clients' view of a pseudo filesystem will server's name space. The clients' view of a pseudo filesystem will
be limited to paths that lead to exported filesystems. be limited to paths that lead to exported filesystems.
skipping to change at page 253, line 7 skipping to change at page 250, line 7
The current filehandle is assumed to refer to a regular directory or The current filehandle is assumed to refer to a regular directory or
a named attribute directory. LOOKUPP assigns the filehandle for its a named attribute directory. LOOKUPP assigns the filehandle for its
parent directory to be the current filehandle. If there is no parent parent directory to be the current filehandle. If there is no parent
directory an NFS4ERR_NOENT error must be returned. Therefore, directory an NFS4ERR_NOENT error must be returned. Therefore,
NFS4ERR_NOENT will be returned by the server when the current NFS4ERR_NOENT will be returned by the server when the current
filehandle is at the root or top of the server's file tree. filehandle is at the root or top of the server's file tree.
15.16.5. IMPLEMENTATION 15.16.5. IMPLEMENTATION
As for LOOKUP, LOOKUPP will also cross mountpoints. As for LOOKUP, LOOKUPP will also cross mount points.
If the current filehandle is not a directory or named attribute If the current filehandle is not a directory or named attribute
directory, the error NFS4ERR_NOTDIR is returned. directory, the error NFS4ERR_NOTDIR is returned.
15.17. Operation 17: NVERIFY - Verify Difference in Attributes 15.17. Operation 17: NVERIFY - Verify Difference in Attributes
15.17.1. SYNOPSIS 15.17.1. SYNOPSIS
(cfh), fattr -> - (cfh), fattr -> -
skipping to change at page 263, line 28 skipping to change at page 260, line 28
should not attempt to second-guess the server's decisions, as access should not attempt to second-guess the server's decisions, as access
rights may change and may be subject to server administrative rights may change and may be subject to server administrative
controls outside the ACL framework. If the requester is not controls outside the ACL framework. If the requester is not
authorized to READ or WRITE (depending on the share_access value), authorized to READ or WRITE (depending on the share_access value),
the server must return NFS4ERR_ACCESS. Note that since the NFS the server must return NFS4ERR_ACCESS. Note that since the NFS
version 4 protocol does not impose any requirement that READs and version 4 protocol does not impose any requirement that READs and
WRITEs issued for an open file have the same credentials as the OPEN WRITEs issued for an open file have the same credentials as the OPEN
itself, the server still must do appropriate access checking on the itself, the server still must do appropriate access checking on the
READs and WRITEs themselves. READs and WRITEs themselves.
If the component provided to OPEN is a symbolic link, the error If the component provided to OPEN resolves to something other than a
NFS4ERR_SYMLINK will be returned to the client. If the current regular file, an error will be returned to the client. If it is a
filehandle is not a directory, the error NFS4ERR_NOTDIR will be directory, NFS4ERR_ISDIR is returned; otherwise, NFS4ERR_SYMLINK is
returned. returned. Note that NFS4ERR_SYMLINK is returned for both symlinks
and for special files of other types; NFS4ERR_INVAL would be
inappropriate, since the arguments provided by the client were
correct, and the client cannot necessarily know at the time it sent
the OPEN that the component would resolve to a non-regular file.
If the current filehandle is not a directory, the error
NFS4ERR_NOTDIR will be returned.
If a COMPOUND contains an OPEN which establishes a If a COMPOUND contains an OPEN which establishes a
OPEN_DELEGATE_WRITE delegation, then a subsequent GETATTR inside that OPEN_DELEGATE_WRITE delegation, then a subsequent GETATTR inside that
COMPOUND SHOULD not result in a CB_GETATTR to the client. The server COMPOUND SHOULD not result in a CB_GETATTR to the client. The server
SHOULD understand the GETATTR to be for the same client ID and avoid SHOULD understand the GETATTR to be for the same client ID and avoid
querying the client, which will not be able to respond. This querying the client, which will not be able to respond. This
sequence of OPEN, GETATTR SHOULD be understood as an atomic retrieval sequence of OPEN, GETATTR SHOULD be understood as an atomic retrieval
of the initial size and change attribute. Further, the client SHOULD of the initial size and change attribute. Further, the client SHOULD
NOT construct a COMPOUND which mixes operations for different client NOT construct a COMPOUND which mixes operations for different client
IDs. IDs.
skipping to change at page 268, line 45 skipping to change at page 266, line 21
15.22.3. RESULT 15.22.3. RESULT
struct PUTFH4res { struct PUTFH4res {
/* CURRENT_FH: */ /* CURRENT_FH: */
nfsstat4 status; nfsstat4 status;
}; };
15.22.4. DESCRIPTION 15.22.4. DESCRIPTION
Replaces the current filehandle with the filehandle provided as an Replaces the current filehandle with the filehandle provided as an
argument. Clears the current stateid. argument.
If the security mechanism used by the requester does not meet the If the security mechanism used by the requester does not meet the
requirements of the filehandle provided to this operation, the server requirements of the filehandle provided to this operation, the server
MUST return NFS4ERR_WRONGSEC. MUST return NFS4ERR_WRONGSEC.
See Section 15.2.4.1 for more details on the current filehandle. See Section 15.2.4.1 for more details on the current filehandle.
See Section 15.2.4.2 for more details on the current stateid.
15.22.5. IMPLEMENTATION 15.22.5. IMPLEMENTATION
Commonly used as the first operator in an NFS request to set the Commonly used as the first operator in an NFS request to set the
context for following operations. context for following operations.
15.23. Operation 23: PUTPUBFH - Set Public Filehandle 15.23. Operation 23: PUTPUBFH - Set Public Filehandle
15.23.1. SYNOPSIS 15.23.1. SYNOPSIS
- -> (cfh) - -> (cfh)
skipping to change at page 271, line 13 skipping to change at page 268, line 30
}; };
15.24.4. DESCRIPTION 15.24.4. DESCRIPTION
Replaces the current filehandle with the filehandle that represents Replaces the current filehandle with the filehandle that represents
the root of the server's name space. From this filehandle a LOOKUP the root of the server's name space. From this filehandle a LOOKUP
operation can locate any other filehandle on the server. This operation can locate any other filehandle on the server. This
filehandle may be different from the "public" filehandle which may be filehandle may be different from the "public" filehandle which may be
associated with some other directory on the server. associated with some other directory on the server.
PUTROOTFH also clears the current stateid.
See Section 15.2.4.1 for more details on the current filehandle. See Section 15.2.4.1 for more details on the current filehandle.
See Section 15.2.4.2 for more details on the current stateid.
15.24.5. IMPLEMENTATION 15.24.5. IMPLEMENTATION
Commonly used as the first operator in an NFS request to set the Commonly used as the first operator in an NFS request to set the
context for following operations. context for following operations.
15.25. Operation 25: READ - Read from File 15.25. Operation 25: READ - Read from File
15.25.1. SYNOPSIS 15.25.1. SYNOPSIS
(cfh), stateid, offset, count -> eof, data (cfh), stateid, offset, count -> eof, data
skipping to change at page 273, line 5 skipping to change at page 270, line 5
If the read ended at the end-of-file (formally, in a correctly formed If the read ended at the end-of-file (formally, in a correctly formed
READ request, if offset + count is equal to the size of the file), or READ request, if offset + count is equal to the size of the file), or
the read request extends beyond the size of the file (if offset + the read request extends beyond the size of the file (if offset +
count is greater than the size of the file), eof is returned as TRUE; count is greater than the size of the file), eof is returned as TRUE;
otherwise it is FALSE. A successful READ of an empty file will otherwise it is FALSE. A successful READ of an empty file will
always return eof as TRUE. always return eof as TRUE.
If the current filehandle is not a regular file, an error will be If the current filehandle is not a regular file, an error will be
returned to the client. In the case the current filehandle returned to the client. In the case the current filehandle
represents a directory, NFS4ERR_ISDIR is return; otherwise, represents a directory, NFS4ERR_ISDIR is returned; otherwise,
NFS4ERR_INVAL is returned. NFS4ERR_INVAL is returned.
For a READ with a stateid value of all bits 0, the server MAY allow For a READ with a stateid value of all bits 0, the server MAY allow
the READ to be serviced subject to mandatory file locks or the the READ to be serviced subject to mandatory file locks or the
current share deny modes for the file. For a READ with a stateid current share deny modes for the file. For a READ with a stateid
value of all bits 1, the server MAY allow READ operations to bypass value of all bits 1, the server MAY allow READ operations to bypass
locking checks at the server. locking checks at the server.
On success, the current filehandle retains its value. On success, the current filehandle retains its value.
skipping to change at page 305, line 13 skipping to change at page 302, line 13
void; void;
15.40.3. RESULT 15.40.3. RESULT
struct ILLEGAL4res { struct ILLEGAL4res {
nfsstat4 status; nfsstat4 status;
}; };
15.40.4. DESCRIPTION 15.40.4. DESCRIPTION
This operation is a placeholder for encoding a result to handle the This operation is a place holder for encoding a result to handle the
case of the client sending an operation code within COMPOUND that is case of the client sending an operation code within COMPOUND that is
not supported. See Section 15.2.4 for more details. not supported. See Section 15.2.4 for more details.
The status field of ILLEGAL4res MUST be set to NFS4ERR_OP_ILLEGAL. The status field of ILLEGAL4res MUST be set to NFS4ERR_OP_ILLEGAL.
15.40.5. IMPLEMENTATION 15.40.5. IMPLEMENTATION
A client will probably not send an operation with code OP_ILLEGAL but A client will probably not send an operation with code OP_ILLEGAL but
if it does, the response will be ILLEGAL4res just as it would be with if it does, the response will be ILLEGAL4res just as it would be with
any other invalid operation code. Note that if the server gets an any other invalid operation code. Note that if the server gets an
skipping to change at page 310, line 26 skipping to change at page 307, line 26
/* /*
* CB_ILLEGAL: Response for illegal operation numbers * CB_ILLEGAL: Response for illegal operation numbers
*/ */
struct CB_ILLEGAL4res { struct CB_ILLEGAL4res {
nfsstat4 status; nfsstat4 status;
}; };
16.2.8.4. DESCRIPTION 16.2.8.4. DESCRIPTION
This operation is a placeholder for encoding a result to handle the This operation is a place-holder for encoding a result to handle the
case of the client sending an operation code within COMPOUND that is case of the client sending an operation code within COMPOUND that is
not supported. See Section 15.2.4 for more details. not supported. See Section 15.2.4 for more details.
The status field of CB_ILLEGAL4res MUST be set to NFS4ERR_OP_ILLEGAL. The status field of CB_ILLEGAL4res MUST be set to NFS4ERR_OP_ILLEGAL.
16.2.8.5. IMPLEMENTATION 16.2.8.5. IMPLEMENTATION
A server will probably not send an operation with code OP_CB_ILLEGAL A server will probably not send an operation with code OP_CB_ILLEGAL
but if it does, the response will be CB_ILLEGAL4res just as it would but if it does, the response will be CB_ILLEGAL4res just as it would
be with any other invalid operation code. Note that if the client be with any other invalid operation code. Note that if the client
skipping to change at page 316, line 11 skipping to change at page 313, line 11
[12] Nowicki, B., "NFS: Network File System Protocol specification", [12] Nowicki, B., "NFS: Network File System Protocol specification",
RFC 1094, March 1989. RFC 1094, March 1989.
[13] Callaghan, B., Pawlowski, B., and P. Staubach, "NFS Version 3 [13] Callaghan, B., Pawlowski, B., and P. Staubach, "NFS Version 3
Protocol Specification", RFC 1813, June 1995. Protocol Specification", RFC 1813, June 1995.
[14] Eisler, M., "XDR: External Data Representation Standard", [14] Eisler, M., "XDR: External Data Representation Standard",
RFC 4506, May 2006. RFC 4506, May 2006.
[15] Linn, J., "The Kerberos Version 5 GSS-API Mechanism", RFC 1964, [15] Zhu, L., Jaganathan, K., and S. Hartman, "The Kerberos Version
June 1996. 5 Generic Security Service Application Program Interface (GSS-
API) Mechanism: Version 2", RFC 4121, July 2005.
[16] Srinivasan, R., "Binding Protocols for ONC RPC Version 2", [16] Srinivasan, R., "Binding Protocols for ONC RPC Version 2",
RFC 1833, August 1995. RFC 1833, August 1995.
[17] Hinden, R. and S. Deering, "IP Version 6 Addressing [17] Hinden, R. and S. Deering, "IP Version 6 Addressing
Architecture", RFC 2373, July 1998. Architecture", RFC 2373, July 1998.
[18] Reynolds, J., "Assigned Numbers: RFC 1700 is Replaced by an On- [18] Reynolds, J., "Assigned Numbers: RFC 1700 is Replaced by an On-
line Database", RFC 3232, January 2002. line Database", RFC 3232, January 2002.
skipping to change at page 318, line 33 skipping to change at page 315, line 33
result. result.
James Lentini graciously read the rewrite of Section 7 and his James Lentini graciously read the rewrite of Section 7 and his
comments were vital in improving the quality of that effort. comments were vital in improving the quality of that effort.
Rob Thurlow, Sorin Faibish, James Lentini, Bruce Fields, and Trond Rob Thurlow, Sorin Faibish, James Lentini, Bruce Fields, and Trond
Myklebust were faithful attendants of the biweekly triage meeting and Myklebust were faithful attendants of the biweekly triage meeting and
accepted many an action item. accepted many an action item.
Bruce Fields was a good sounding board for both the Third Edge Bruce Fields was a good sounding board for both the Third Edge
Condition and Courtsey Locks in general. Condition and Courtesy Locks in general. He was also the leading
advocate of stamping out backport issues from [29].
Marcel Telka was a champion of straightening out the difference Marcel Telka was a champion of straightening out the difference
between a lock-owner and an open-owner. He has also been diligent in between a lock-owner and an open-owner. He has also been diligent in
reviewing the final document. reviewing the final document.
Appendix B. RFC Editor Notes Appendix B. RFC Editor Notes
[RFC Editor: please remove this section prior to publishing this [RFC Editor: please remove this section prior to publishing this
document as an RFC] document as an RFC]
[RFC Editor: prior to publishing this document as an RFC, please [RFC Editor: prior to publishing this document as an RFC, please
replace all occurences of RFCNFSv4XDR with RFCxxxx where xxxx is the replace all occurrences of RFCNFSv4XDR with RFCxxxx where xxxx is the
RFC number assigned to the XDR document.] RFC number assigned to the XDR document.]
[RFC Editor: Please note that there is also a reference entry that [RFC Editor: Please note that there is also a reference entry that
needs to be modified for the companion document.] needs to be modified for the companion document.]
Authors' Addresses Authors' Addresses
Thomas Haynes (editor) Thomas Haynes (editor)
NetApp NetApp
9110 E 66th St 9110 E 66th St
 End of changes. 79 change blocks. 
497 lines changed or deleted 330 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/