draft-ietf-nfsv4-rfc3530bis-34.txt   draft-ietf-nfsv4-rfc3530bis-35.txt 
NFSv4 T. Haynes, Ed. NFSv4 T. Haynes, Ed.
Internet-Draft Primary Data Internet-Draft Primary Data
Obsoletes: 3530 (if approved) D. Noveck, Ed. Obsoletes: 3530 (if approved) D. Noveck, Ed.
Intended status: Standards Track Dell Intended status: Standards Track Dell
Expires: May 14, 2015 November 10, 2014 Expires: June 7, 2015 December 04, 2014
Network File System (NFS) Version 4 Protocol Network File System (NFS) Version 4 Protocol
draft-ietf-nfsv4-rfc3530bis-34.txt draft-ietf-nfsv4-rfc3530bis-35.txt
Abstract Abstract
The Network File System (NFS) version 4 is a distributed file system The Network File System (NFS) version 4 is a distributed file system
protocol which builds on the heritage of NFS protocol version 2, RFC protocol which builds on the heritage of NFS protocol version 2, RFC
1094, and version 3, RFC 1813. Unlike earlier versions, the NFS 1094, and version 3, RFC 1813. Unlike earlier versions, the NFS
version 4 protocol supports traditional file access while integrating version 4 protocol supports traditional file access while integrating
support for file locking and the mount protocol. In addition, support for file locking and the mount protocol. In addition,
support for strong security (and its negotiation), compound support for strong security (and its negotiation), compound
operations, client caching, and internationalization have been added. operations, client caching, and internationalization have been added.
skipping to change at page 1, line 32 skipping to change at page 1, line 32
well in an Internet environment. well in an Internet environment.
This document, together with the companion XDR description document, This document, together with the companion XDR description document,
RFCNFSv4XDR, obsoletes RFC 3530 as the definition of the NFS version RFCNFSv4XDR, obsoletes RFC 3530 as the definition of the NFS version
4 protocol. 4 protocol.
Requirements Language Requirements Language
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119 [RFC2119]. document are to be interpreted as described in RFC 2119 [RFC2119]
except where "REQUIRED" and "RECOMMENDED" are used as qualifiers to
distinguish classes of attributes as described in Section 1.3.3.2 and
Section 5.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
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 May 14, 2015. This Internet-Draft will expire on June 7, 2015.
Copyright Notice Copyright Notice
Copyright (c) 2014 IETF Trust and the persons identified as the Copyright (c) 2014 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 2, line 47 skipping to change at page 2, line 51
Protocol are Authoritative . . . . . . . . . . . . . . . 8 Protocol are Authoritative . . . . . . . . . . . . . . . 8
1.3. Overview of NFSv4 Features . . . . . . . . . . . . . . . 8 1.3. Overview of NFSv4 Features . . . . . . . . . . . . . . . 8
1.3.1. RPC and Security . . . . . . . . . . . . . . . . . . 9 1.3.1. RPC and Security . . . . . . . . . . . . . . . . . . 9
1.3.2. Procedure and Operation Structure . . . . . . . . . . 9 1.3.2. Procedure and Operation Structure . . . . . . . . . . 9
1.3.3. Filesystem Model . . . . . . . . . . . . . . . . . . 10 1.3.3. Filesystem Model . . . . . . . . . . . . . . . . . . 10
1.3.4. OPEN and CLOSE . . . . . . . . . . . . . . . . . . . 12 1.3.4. OPEN and CLOSE . . . . . . . . . . . . . . . . . . . 12
1.3.5. File Locking . . . . . . . . . . . . . . . . . . . . 12 1.3.5. File Locking . . . . . . . . . . . . . . . . . . . . 12
1.3.6. Client Caching and Delegation . . . . . . . . . . . . 12 1.3.6. Client Caching and Delegation . . . . . . . . . . . . 12
1.4. General Definitions . . . . . . . . . . . . . . . . . . . 13 1.4. General Definitions . . . . . . . . . . . . . . . . . . . 13
1.5. Changes since RFC 3530 . . . . . . . . . . . . . . . . . 15 1.5. Changes since RFC 3530 . . . . . . . . . . . . . . . . . 15
1.6. Changes between RFC 3010 and RFC3530 . . . . . . . . . . 15 1.6. Changes between RFC 3010 and RFC3530 . . . . . . . . . . 16
2. Protocol Data Types . . . . . . . . . . . . . . . . . . . . . 16
2.1. Basic Data Types . . . . . . . . . . . . . . . . . . . . 16 2. Protocol Data Types . . . . . . . . . . . . . . . . . . . . . 17
2.2. Structured Data Types . . . . . . . . . . . . . . . . . . 18 2.1. Basic Data Types . . . . . . . . . . . . . . . . . . . . 17
3. RPC and Security Flavor . . . . . . . . . . . . . . . . . . . 22 2.2. Structured Data Types . . . . . . . . . . . . . . . . . . 19
3.1. Ports and Transports . . . . . . . . . . . . . . . . . . 22 3. RPC and Security Flavor . . . . . . . . . . . . . . . . . . . 23
3.1.1. Client Retransmission Behavior . . . . . . . . . . . 23 3.1. Ports and Transports . . . . . . . . . . . . . . . . . . 23
3.2. Security Flavors . . . . . . . . . . . . . . . . . . . . 24 3.1.1. Client Retransmission Behavior . . . . . . . . . . . 24
3.2.1. Security mechanisms for NFSv4 . . . . . . . . . . . . 24 3.2. Security Flavors . . . . . . . . . . . . . . . . . . . . 25
3.3. Security Negotiation . . . . . . . . . . . . . . . . . . 25 3.2.1. Security mechanisms for NFSv4 . . . . . . . . . . . . 25
3.3.1. SECINFO . . . . . . . . . . . . . . . . . . . . . . . 26 3.3. Security Negotiation . . . . . . . . . . . . . . . . . . 26
3.3.2. Security Error . . . . . . . . . . . . . . . . . . . 26 3.3.1. SECINFO . . . . . . . . . . . . . . . . . . . . . . . 27
3.3.3. Callback RPC Authentication . . . . . . . . . . . . . 26 3.3.2. Security Error . . . . . . . . . . . . . . . . . . . 27
4. Filehandles . . . . . . . . . . . . . . . . . . . . . . . . . 27 3.3.3. Callback RPC Authentication . . . . . . . . . . . . . 27
4. Filehandles . . . . . . . . . . . . . . . . . . . . . . . . . 28
4.1. Obtaining the First Filehandle . . . . . . . . . . . . . 28 4.1. Obtaining the First Filehandle . . . . . . . . . . . . . 28
4.1.1. Root Filehandle . . . . . . . . . . . . . . . . . . . 28 4.1.1. Root Filehandle . . . . . . . . . . . . . . . . . . . 29
4.1.2. Public Filehandle . . . . . . . . . . . . . . . . . . 28 4.1.2. Public Filehandle . . . . . . . . . . . . . . . . . . 29
4.2. Filehandle Types . . . . . . . . . . . . . . . . . . . . 29 4.2. Filehandle Types . . . . . . . . . . . . . . . . . . . . 29
4.2.1. General Properties of a Filehandle . . . . . . . . . 29 4.2.1. General Properties of a Filehandle . . . . . . . . . 30
4.2.2. Persistent Filehandle . . . . . . . . . . . . . . . . 30 4.2.2. Persistent Filehandle . . . . . . . . . . . . . . . . 30
4.2.3. Volatile Filehandle . . . . . . . . . . . . . . . . . 30 4.2.3. Volatile Filehandle . . . . . . . . . . . . . . . . . 31
4.2.4. One Method of Constructing a Volatile Filehandle . . 31 4.2.4. One Method of Constructing a Volatile Filehandle . . 32
4.3. Client Recovery from Filehandle Expiration . . . . . . . 32 4.3. Client Recovery from Filehandle Expiration . . . . . . . 33
5. Attributes . . . . . . . . . . . . . . . . . . . . . . . . . 33 5. Attributes . . . . . . . . . . . . . . . . . . . . . . . . . 33
5.1. REQUIRED Attributes . . . . . . . . . . . . . . . . . . . 34 5.1. REQUIRED Attributes . . . . . . . . . . . . . . . . . . . 35
5.2. RECOMMENDED Attributes . . . . . . . . . . . . . . . . . 34 5.2. RECOMMENDED Attributes . . . . . . . . . . . . . . . . . 35
5.3. Named Attributes . . . . . . . . . . . . . . . . . . . . 35 5.3. Named Attributes . . . . . . . . . . . . . . . . . . . . 35
5.4. Classification of Attributes . . . . . . . . . . . . . . 36 5.4. Classification of Attributes . . . . . . . . . . . . . . 37
5.5. Set-Only and Get-Only Attributes . . . . . . . . . . . . 37 5.5. Set-Only and Get-Only Attributes . . . . . . . . . . . . 38
5.6. REQUIRED Attributes - List and Definition References . . 38 5.6. REQUIRED Attributes - List and Definition References . . 38
5.7. RECOMMENDED Attributes - List and Definition References . 38 5.7. RECOMMENDED Attributes - List and Definition References . 39
5.8. Attribute Definitions . . . . . . . . . . . . . . . . . . 40 5.8. Attribute Definitions . . . . . . . . . . . . . . . . . . 41
5.8.1. Definitions of REQUIRED Attributes . . . . . . . . . 40 5.8.1. Definitions of REQUIRED Attributes . . . . . . . . . 41
5.8.2. Definitions of Uncategorized RECOMMENDED Attributes . 42 5.8.2. Definitions of Uncategorized RECOMMENDED Attributes . 43
5.9. Interpreting owner and owner_group . . . . . . . . . . . 48 5.9. Interpreting owner and owner_group . . . . . . . . . . . 49
5.10. Character Case Attributes . . . . . . . . . . . . . . . . 51 5.10. Character Case Attributes . . . . . . . . . . . . . . . . 52
6. Access Control Attributes . . . . . . . . . . . . . . . . . . 51 6. Access Control Attributes . . . . . . . . . . . . . . . . . . 52
6.1. Goals . . . . . . . . . . . . . . . . . . . . . . . . . . 52 6.1. Goals . . . . . . . . . . . . . . . . . . . . . . . . . . 52
6.2. File Attributes Discussion . . . . . . . . . . . . . . . 52 6.2. File Attributes Discussion . . . . . . . . . . . . . . . 53
6.2.1. Attribute 12: acl . . . . . . . . . . . . . . . . . . 53 6.2.1. Attribute 12: acl . . . . . . . . . . . . . . . . . . 53
6.2.2. Attribute 33: mode . . . . . . . . . . . . . . . . . 67 6.2.2. Attribute 33: mode . . . . . . . . . . . . . . . . . 68
6.3. Common Methods . . . . . . . . . . . . . . . . . . . . . 67 6.3. Common Methods . . . . . . . . . . . . . . . . . . . . . 68
6.3.1. Interpreting an ACL . . . . . . . . . . . . . . . . . 67 6.3.1. Interpreting an ACL . . . . . . . . . . . . . . . . . 68
6.3.2. Computing a Mode Attribute from an ACL . . . . . . . 68 6.3.2. Computing a Mode Attribute from an ACL . . . . . . . 69
6.4. Requirements . . . . . . . . . . . . . . . . . . . . . . 69 6.4. Requirements . . . . . . . . . . . . . . . . . . . . . . 70
6.4.1. Setting the mode and/or ACL Attributes . . . . . . . 70 6.4.1. Setting the mode and/or ACL Attributes . . . . . . . 71
6.4.2. Retrieving the mode and/or ACL Attributes . . . . . . 71 6.4.2. Retrieving the mode and/or ACL Attributes . . . . . . 72
6.4.3. Creating New Objects . . . . . . . . . . . . . . . . 71 6.4.3. Creating New Objects . . . . . . . . . . . . . . . . 72
7. NFS Server Name Space . . . . . . . . . . . . . . . . . . . . 73 7. NFS Server Name Space . . . . . . . . . . . . . . . . . . . . 74
7.1. Server Exports . . . . . . . . . . . . . . . . . . . . . 73 7.1. Server Exports . . . . . . . . . . . . . . . . . . . . . 74
7.2. Browsing Exports . . . . . . . . . . . . . . . . . . . . 74 7.2. Browsing Exports . . . . . . . . . . . . . . . . . . . . 75
7.3. Server Pseudo Filesystem . . . . . . . . . . . . . . . . 74 7.3. Server Pseudo Filesystem . . . . . . . . . . . . . . . . 75
7.4. Multiple Roots . . . . . . . . . . . . . . . . . . . . . 75 7.4. Multiple Roots . . . . . . . . . . . . . . . . . . . . . 76
7.5. Filehandle Volatility . . . . . . . . . . . . . . . . . . 75 7.5. Filehandle Volatility . . . . . . . . . . . . . . . . . . 76
7.6. Exported Root . . . . . . . . . . . . . . . . . . . . . . 75 7.6. Exported Root . . . . . . . . . . . . . . . . . . . . . . 76
7.7. Mount Point Crossing . . . . . . . . . . . . . . . . . . 75 7.7. Mount Point Crossing . . . . . . . . . . . . . . . . . . 76
7.8. Security Policy and Name Space Presentation . . . . . . . 76 7.8. Security Policy and Name Space Presentation . . . . . . . 77
8. Multi-Server Namespace . . . . . . . . . . . . . . . . . . . 77 8. Multi-Server Namespace . . . . . . . . . . . . . . . . . . . 78
8.1. Location Attributes . . . . . . . . . . . . . . . . . . . 77 8.1. Location Attributes . . . . . . . . . . . . . . . . . . . 78
8.2. File System Presence or Absence . . . . . . . . . . . . . 77 8.2. File System Presence or Absence . . . . . . . . . . . . . 78
8.3. Getting Attributes for an Absent File System . . . . . . 78 8.3. Getting Attributes for an Absent File System . . . . . . 79
8.3.1. GETATTR Within an Absent File System . . . . . . . . 78 8.3.1. GETATTR Within an Absent File System . . . . . . . . 80
8.3.2. READDIR and Absent File Systems . . . . . . . . . . . 79 8.3.2. READDIR and Absent File Systems . . . . . . . . . . . 81
8.4. Uses of Location Information . . . . . . . . . . . . . . 80 8.4. Uses of Location Information . . . . . . . . . . . . . . 81
8.4.1. File System Replication . . . . . . . . . . . . . . . 81 8.4.1. File System Replication . . . . . . . . . . . . . . . 82
8.4.2. File System Migration . . . . . . . . . . . . . . . . 81 8.4.2. File System Migration . . . . . . . . . . . . . . . . 83
8.4.3. Referrals . . . . . . . . . . . . . . . . . . . . . . 82 8.4.3. Referrals . . . . . . . . . . . . . . . . . . . . . . 83
8.5. Location Entries and Server Identity . . . . . . . . . . 83 8.5. Location Entries and Server Identity . . . . . . . . . . 84
8.6. Additional Client-Side Considerations . . . . . . . . . . 83 8.6. Additional Client-Side Considerations . . . . . . . . . . 85
8.7. Effecting File System Referrals . . . . . . . . . . . . . 84 8.7. Effecting File System Referrals . . . . . . . . . . . . . 86
8.7.1. Referral Example (LOOKUP) . . . . . . . . . . . . . . 85 8.7.1. Referral Example (LOOKUP) . . . . . . . . . . . . . . 86
8.7.2. Referral Example (READDIR) . . . . . . . . . . . . . 89 8.7.2. Referral Example (READDIR) . . . . . . . . . . . . . 90
8.8. The Attribute fs_locations . . . . . . . . . . . . . . . 91 8.8. The Attribute fs_locations . . . . . . . . . . . . . . . 92
8.8.1. Inferring Transition Modes . . . . . . . . . . . . . 93
9. File Locking and Share Reservations . . . . . . . . . . . . . 94 9. File Locking and Share Reservations . . . . . . . . . . . . . 94
9.1. Opens and Byte-Range Locks . . . . . . . . . . . . . . . 95 9.1. Opens and Byte-Range Locks . . . . . . . . . . . . . . . 95
9.1.1. Client ID . . . . . . . . . . . . . . . . . . . . . . 95 9.1.1. Client ID . . . . . . . . . . . . . . . . . . . . . . 95
9.1.2. Server Release of Client ID . . . . . . . . . . . . . 98 9.1.2. Server Release of Client ID . . . . . . . . . . . . . 98
9.1.3. Stateid Definition . . . . . . . . . . . . . . . . . 99 9.1.3. Use of Seqids . . . . . . . . . . . . . . . . . . . . 99
9.1.4. lock-owner . . . . . . . . . . . . . . . . . . . . . 105 9.1.4. Stateid Definition . . . . . . . . . . . . . . . . . 100
9.1.5. Use of the Stateid and Locking . . . . . . . . . . . 106 9.1.5. lock-owner . . . . . . . . . . . . . . . . . . . . . 106
9.1.6. Sequencing of Lock Requests . . . . . . . . . . . . . 108 9.1.6. Use of the Stateid and Locking . . . . . . . . . . . 107
9.1.7. Recovery from Replayed Requests . . . . . . . . . . . 109 9.1.7. Sequencing of Lock Requests . . . . . . . . . . . . . 109
9.1.8. Interactions of multiple sequence values . . . . . . 109 9.1.8. Recovery from Replayed Requests . . . . . . . . . . . 110
9.1.9. Releasing state-owner State . . . . . . . . . . . . . 110 9.1.9. Interactions of multiple sequence values . . . . . . 110
9.1.10. Use of Open Confirmation . . . . . . . . . . . . . . 111 9.1.10. Releasing state-owner State . . . . . . . . . . . . . 111
9.2. Lock Ranges . . . . . . . . . . . . . . . . . . . . . . . 112 9.1.11. Use of Open Confirmation . . . . . . . . . . . . . . 112
9.3. Upgrading and Downgrading Locks . . . . . . . . . . . . . 112 9.2. Lock Ranges . . . . . . . . . . . . . . . . . . . . . . . 113
9.4. Blocking Locks . . . . . . . . . . . . . . . . . . . . . 113 9.3. Upgrading and Downgrading Locks . . . . . . . . . . . . . 113
9.5. Lease Renewal . . . . . . . . . . . . . . . . . . . . . . 114 9.4. Blocking Locks . . . . . . . . . . . . . . . . . . . . . 114
9.6. Crash Recovery . . . . . . . . . . . . . . . . . . . . . 115 9.5. Lease Renewal . . . . . . . . . . . . . . . . . . . . . . 115
9.6.1. Client Failure and Recovery . . . . . . . . . . . . . 115 9.6. Crash Recovery . . . . . . . . . . . . . . . . . . . . . 116
9.6.2. Server Failure and Recovery . . . . . . . . . . . . . 115 9.6.1. Client Failure and Recovery . . . . . . . . . . . . . 116
9.6.3. Network Partitions and Recovery . . . . . . . . . . . 117 9.6.2. Server Failure and Recovery . . . . . . . . . . . . . 116
9.7. Recovery from a Lock Request Timeout or Abort . . . . . . 125 9.6.3. Network Partitions and Recovery . . . . . . . . . . . 118
9.8. Server Revocation of Locks . . . . . . . . . . . . . . . 125 9.7. Recovery from a Lock Request Timeout or Abort . . . . . . 126
9.9. Share Reservations . . . . . . . . . . . . . . . . . . . 127 9.8. Server Revocation of Locks . . . . . . . . . . . . . . . 126
9.10. OPEN/CLOSE Operations . . . . . . . . . . . . . . . . . . 127 9.9. Share Reservations . . . . . . . . . . . . . . . . . . . 128
9.10.1. Close and Retention of State Information . . . . . . 128 9.10. OPEN/CLOSE Operations . . . . . . . . . . . . . . . . . . 128
9.11. Open Upgrade and Downgrade . . . . . . . . . . . . . . . 129 9.10.1. Close and Retention of State Information . . . . . . 129
9.12. Short and Long Leases . . . . . . . . . . . . . . . . . . 129 9.11. Open Upgrade and Downgrade . . . . . . . . . . . . . . . 130
9.12. Short and Long Leases . . . . . . . . . . . . . . . . . . 130
9.13. Clocks, Propagation Delay, and Calculating Lease 9.13. Clocks, Propagation Delay, and Calculating Lease
Expiration . . . . . . . . . . . . . . . . . . . . . . . 130 Expiration . . . . . . . . . . . . . . . . . . . . . . . 131
9.14. Migration, Replication and State . . . . . . . . . . . . 130 9.14. Migration, Replication and State . . . . . . . . . . . . 131
9.14.1. Migration and State . . . . . . . . . . . . . . . . 131 9.14.1. Migration and State . . . . . . . . . . . . . . . . 132
9.14.2. Replication and State . . . . . . . . . . . . . . . 132 9.14.2. Replication and State . . . . . . . . . . . . . . . 133
9.14.3. Notification of Migrated Lease . . . . . . . . . . . 132 9.14.3. Notification of Migrated Lease . . . . . . . . . . . 133
9.14.4. Migration and the Lease_time Attribute . . . . . . . 133 9.14.4. Migration and the lease_time Attribute . . . . . . . 134
10. Client-Side Caching . . . . . . . . . . . . . . . . . . . . . 133 10. Client-Side Caching . . . . . . . . . . . . . . . . . . . . . 135
10.1. Performance Challenges for Client-Side Caching . . . . . 134 10.1. Performance Challenges for Client-Side Caching . . . . . 135
10.2. Delegation and Callbacks . . . . . . . . . . . . . . . . 135 10.2. Delegation and Callbacks . . . . . . . . . . . . . . . . 136
10.2.1. Delegation Recovery . . . . . . . . . . . . . . . . 137 10.2.1. Delegation Recovery . . . . . . . . . . . . . . . . 138
10.3. Data Caching . . . . . . . . . . . . . . . . . . . . . . 141 10.3. Data Caching . . . . . . . . . . . . . . . . . . . . . . 142
10.3.1. Data Caching and OPENs . . . . . . . . . . . . . . . 141 10.3.1. Data Caching and OPENs . . . . . . . . . . . . . . . 143
10.3.2. Data Caching and File Locking . . . . . . . . . . . 142 10.3.2. Data Caching and File Locking . . . . . . . . . . . 144
10.3.3. Data Caching and Mandatory File Locking . . . . . . 144 10.3.3. Data Caching and Mandatory File Locking . . . . . . 145
10.3.4. Data Caching and File Identity . . . . . . . . . . . 144 10.3.4. Data Caching and File Identity . . . . . . . . . . . 146
10.4. Open Delegation . . . . . . . . . . . . . . . . . . . . 146 10.4. Open Delegation . . . . . . . . . . . . . . . . . . . . 147
10.4.1. Open Delegation and Data Caching . . . . . . . . . . 148 10.4.1. Open Delegation and Data Caching . . . . . . . . . . 149
10.4.2. Open Delegation and File Locks . . . . . . . . . . . 149 10.4.2. Open Delegation and File Locks . . . . . . . . . . . 151
10.4.3. Handling of CB_GETATTR . . . . . . . . . . . . . . . 150 10.4.3. Handling of CB_GETATTR . . . . . . . . . . . . . . . 151
10.4.4. Recall of Open Delegation . . . . . . . . . . . . . 153 10.4.4. Recall of Open Delegation . . . . . . . . . . . . . 154
10.4.5. OPEN Delegation Race with CB_RECALL . . . . . . . . 155 10.4.5. OPEN Delegation Race with CB_RECALL . . . . . . . . 156
10.4.6. Clients that Fail to Honor Delegation Recalls . . . 155 10.4.6. Clients that Fail to Honor Delegation Recalls . . . 157
10.4.7. Delegation Revocation . . . . . . . . . . . . . . . 156 10.4.7. Delegation Revocation . . . . . . . . . . . . . . . 158
10.5. Data Caching and Revocation . . . . . . . . . . . . . . 157 10.5. Data Caching and Revocation . . . . . . . . . . . . . . 158
10.5.1. Revocation Recovery for Write Open Delegation . . . 157 10.5.1. Revocation Recovery for Write Open Delegation . . . 159
10.6. Attribute Caching . . . . . . . . . . . . . . . . . . . 158 10.6. Attribute Caching . . . . . . . . . . . . . . . . . . . 159
10.7. Data and Metadata Caching and Memory Mapped Files . . . 160 10.7. Data and Metadata Caching and Memory Mapped Files . . . 161
10.8. Name Caching . . . . . . . . . . . . . . . . . . . . . . 162 10.8. Name Caching . . . . . . . . . . . . . . . . . . . . . . 163
10.9. Directory Caching . . . . . . . . . . . . . . . . . . . 163 10.9. Directory Caching . . . . . . . . . . . . . . . . . . . 164
11. Minor Versioning . . . . . . . . . . . . . . . . . . . . . . 164 11. Minor Versioning . . . . . . . . . . . . . . . . . . . . . . 165
12. Internationalization . . . . . . . . . . . . . . . . . . . . 165 12. Internationalization . . . . . . . . . . . . . . . . . . . . 166
12.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 165 12.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 166
12.2. Limitations on internationalization-related processing 12.2. Limitations on internationalization-related processing
in the NFSv4 context . . . . . . . . . . . . . . . . . . 166 in the NFSv4 context . . . . . . . . . . . . . . . . . . 168
12.3. Summary of Server Behavior Types . . . . . . . . . . . . 167 12.3. Summary of Server Behavior Types . . . . . . . . . . . . 168
12.4. String Encoding . . . . . . . . . . . . . . . . . . . . 168 12.4. String Encoding . . . . . . . . . . . . . . . . . . . . 169
12.5. Normalization . . . . . . . . . . . . . . . . . . . . . 169 12.5. Normalization . . . . . . . . . . . . . . . . . . . . . 170
12.6. Types with Processing Defined by Other Internet Areas . 169 12.6. Types with Processing Defined by Other Internet Areas . 171
12.7. UTF-8 Related Errors . . . . . . . . . . . . . . . . . . 171 12.7. UTF-8 Related Errors . . . . . . . . . . . . . . . . . . 172
12.8. Servers that accept file component names that are not 12.8. Servers that accept file component names that are not
valid UTF-8 strings . . . . . . . . . . . . . . . . . . 171 valid UTF-8 strings . . . . . . . . . . . . . . . . . . 173
13. Error Values . . . . . . . . . . . . . . . . . . . . . . . . 172 13. Error Values . . . . . . . . . . . . . . . . . . . . . . . . 174
13.1. Error Definitions . . . . . . . . . . . . . . . . . . . 172 13.1. Error Definitions . . . . . . . . . . . . . . . . . . . 174
13.1.1. General Errors . . . . . . . . . . . . . . . . . . . 174 13.1.1. General Errors . . . . . . . . . . . . . . . . . . . 175
13.1.2. Filehandle Errors . . . . . . . . . . . . . . . . . 175 13.1.2. Filehandle Errors . . . . . . . . . . . . . . . . . 177
13.1.3. Compound Structure Errors . . . . . . . . . . . . . 176 13.1.3. Compound Structure Errors . . . . . . . . . . . . . 178
13.1.4. File System Errors . . . . . . . . . . . . . . . . . 177 13.1.4. File System Errors . . . . . . . . . . . . . . . . . 179
13.1.5. State Management Errors . . . . . . . . . . . . . . 179 13.1.5. State Management Errors . . . . . . . . . . . . . . 181
13.1.6. Security Errors . . . . . . . . . . . . . . . . . . 180 13.1.6. Security Errors . . . . . . . . . . . . . . . . . . 182
13.1.7. Name Errors . . . . . . . . . . . . . . . . . . . . 181 13.1.7. Name Errors . . . . . . . . . . . . . . . . . . . . 183
13.1.8. Locking Errors . . . . . . . . . . . . . . . . . . . 182 13.1.8. Locking Errors . . . . . . . . . . . . . . . . . . . 183
13.1.9. Reclaim Errors . . . . . . . . . . . . . . . . . . . 183 13.1.9. Reclaim Errors . . . . . . . . . . . . . . . . . . . 185
13.1.10. Client Management Errors . . . . . . . . . . . . . . 184 13.1.10. Client Management Errors . . . . . . . . . . . . . . 186
13.1.11. Attribute Handling Errors . . . . . . . . . . . . . 184 13.1.11. Attribute Handling Errors . . . . . . . . . . . . . 186
13.2. Operations and their valid errors . . . . . . . . . . . 185 13.1.12. Miscellaneous Errors . . . . . . . . . . . . . . . . 187
13.3. Callback operations and their valid errors . . . . . . . 192 13.2. Operations and their valid errors . . . . . . . . . . . 187
13.4. Errors and the operations that use them . . . . . . . . 193 13.3. Callback operations and their valid errors . . . . . . . 194
14. NFSv4 Requests . . . . . . . . . . . . . . . . . . . . . . . 198 13.4. Errors and the operations that use them . . . . . . . . 195
14.1. Compound Procedure . . . . . . . . . . . . . . . . . . . 199 14. NFSv4 Requests . . . . . . . . . . . . . . . . . . . . . . . 200
14.2. Evaluation of a Compound Request . . . . . . . . . . . . 200 14.1. Compound Procedure . . . . . . . . . . . . . . . . . . . 201
14.3. Synchronous Modifying Operations . . . . . . . . . . . . 200 14.2. Evaluation of a Compound Request . . . . . . . . . . . . 202
14.4. Operation Values . . . . . . . . . . . . . . . . . . . . 201 14.3. Synchronous Modifying Operations . . . . . . . . . . . . 202
15. NFSv4 Procedures . . . . . . . . . . . . . . . . . . . . . . 201 14.4. Operation Values . . . . . . . . . . . . . . . . . . . . 203
15.1. Procedure 0: NULL - No Operation . . . . . . . . . . . . 201 15. NFSv4 Procedures . . . . . . . . . . . . . . . . . . . . . . 203
15.2. Procedure 1: COMPOUND - Compound Operations . . . . . . 201 15.1. Procedure 0: NULL - No Operation . . . . . . . . . . . . 203
15.3. Operation 3: ACCESS - Check Access Rights . . . . . . . 205 15.2. Procedure 1: COMPOUND - Compound Operations . . . . . . 203
15.4. Operation 4: CLOSE - Close File . . . . . . . . . . . . 208 15.3. Operation 3: ACCESS - Check Access Rights . . . . . . . 207
15.5. Operation 5: COMMIT - Commit Cached Data . . . . . . . . 209 15.4. Operation 4: CLOSE - Close File . . . . . . . . . . . . 210
15.6. Operation 6: CREATE - Create a Non-Regular File Object . 211 15.5. Operation 5: COMMIT - Commit Cached Data . . . . . . . . 211
15.6. Operation 6: CREATE - Create a Non-Regular File Object . 213
15.7. Operation 7: DELEGPURGE - Purge Delegations Awaiting 15.7. Operation 7: DELEGPURGE - Purge Delegations Awaiting
Recovery . . . . . . . . . . . . . . . . . . . . . . . . 214 Recovery . . . . . . . . . . . . . . . . . . . . . . . . 216
15.8. Operation 8: DELEGRETURN - Return Delegation . . . . . . 215 15.8. Operation 8: DELEGRETURN - Return Delegation . . . . . . 217
15.9. Operation 9: GETATTR - Get Attributes . . . . . . . . . 216 15.9. Operation 9: GETATTR - Get Attributes . . . . . . . . . 218
15.10. Operation 10: GETFH - Get Current Filehandle . . . . . . 218 15.10. Operation 10: GETFH - Get Current Filehandle . . . . . . 220
15.11. Operation 11: LINK - Create Link to a File . . . . . . . 218 15.11. Operation 11: LINK - Create Link to a File . . . . . . . 220
15.12. Operation 12: LOCK - Create Lock . . . . . . . . . . . . 220 15.12. Operation 12: LOCK - Create Lock . . . . . . . . . . . . 222
15.13. Operation 13: LOCKT - Test For Lock . . . . . . . . . . 224 15.13. Operation 13: LOCKT - Test For Lock . . . . . . . . . . 226
15.14. Operation 14: LOCKU - Unlock File . . . . . . . . . . . 226 15.14. Operation 14: LOCKU - Unlock File . . . . . . . . . . . 228
15.15. Operation 15: LOOKUP - Lookup Filename . . . . . . . . . 227 15.15. Operation 15: LOOKUP - Lookup Filename . . . . . . . . . 229
15.16. Operation 16: LOOKUPP - Lookup Parent Directory . . . . 229 15.16. Operation 16: LOOKUPP - Lookup Parent Directory . . . . 231
15.17. Operation 17: NVERIFY - Verify Difference in Attributes 230 15.17. Operation 17: NVERIFY - Verify Difference in Attributes 232
15.18. Operation 18: OPEN - Open a Regular File . . . . . . . . 231 15.18. Operation 18: OPEN - Open a Regular File . . . . . . . . 233
15.19. Operation 19: OPENATTR - Open Named Attribute Directory 241 15.19. Operation 19: OPENATTR - Open Named Attribute Directory 243
15.20. Operation 20: OPEN_CONFIRM - Confirm Open . . . . . . . 242 15.20. Operation 20: OPEN_CONFIRM - Confirm Open . . . . . . . 244
15.21. Operation 21: OPEN_DOWNGRADE - Reduce Open File Access . 244 15.21. Operation 21: OPEN_DOWNGRADE - Reduce Open File Access . 246
15.22. Operation 22: PUTFH - Set Current Filehandle . . . . . . 246 15.22. Operation 22: PUTFH - Set Current Filehandle . . . . . . 248
15.23. Operation 23: PUTPUBFH - Set Public Filehandle . . . . . 246 15.23. Operation 23: PUTPUBFH - Set Public Filehandle . . . . . 248
15.24. Operation 24: PUTROOTFH - Set Root Filehandle . . . . . 248 15.24. Operation 24: PUTROOTFH - Set Root Filehandle . . . . . 250
15.25. Operation 25: READ - Read from File . . . . . . . . . . 249 15.25. Operation 25: READ - Read from File . . . . . . . . . . 251
15.26. Operation 26: READDIR - Read Directory . . . . . . . . . 251 15.26. Operation 26: READDIR - Read Directory . . . . . . . . . 253
15.27. Operation 27: READLINK - Read Symbolic Link . . . . . . 255 15.27. Operation 27: READLINK - Read Symbolic Link . . . . . . 257
15.28. Operation 28: REMOVE - Remove Filesystem Object . . . . 256 15.28. Operation 28: REMOVE - Remove Filesystem Object . . . . 258
15.29. Operation 29: RENAME - Rename Directory Entry . . . . . 257 15.29. Operation 29: RENAME - Rename Directory Entry . . . . . 260
15.30. Operation 30: RENEW - Renew a Lease . . . . . . . . . . 259 15.30. Operation 30: RENEW - Renew a Lease . . . . . . . . . . 262
15.31. Operation 31: RESTOREFH - Restore Saved Filehandle . . . 261 15.31. Operation 31: RESTOREFH - Restore Saved Filehandle . . . 263
15.32. Operation 32: SAVEFH - Save Current Filehandle . . . . . 262 15.32. Operation 32: SAVEFH - Save Current Filehandle . . . . . 264
15.33. Operation 33: SECINFO - Obtain Available Security . . . 262 15.33. Operation 33: SECINFO - Obtain Available Security . . . 265
15.34. Operation 34: SETATTR - Set Attributes . . . . . . . . . 266 15.34. Operation 34: SETATTR - Set Attributes . . . . . . . . . 268
15.35. Operation 35: SETCLIENTID - Negotiate Client ID . . . . 268 15.35. Operation 35: SETCLIENTID - Negotiate Client ID . . . . 271
15.36. Operation 36: SETCLIENTID_CONFIRM - Confirm Client ID . 272 15.36. Operation 36: SETCLIENTID_CONFIRM - Confirm Client ID . 275
15.37. Operation 37: VERIFY - Verify Same Attributes . . . . . 275 15.37. Operation 37: VERIFY - Verify Same Attributes . . . . . 278
15.38. Operation 38: WRITE - Write to File . . . . . . . . . . 277 15.38. Operation 38: WRITE - Write to File . . . . . . . . . . 280
15.39. Operation 39: RELEASE_LOCKOWNER - Release Lockowner 15.39. Operation 39: RELEASE_LOCKOWNER - Release Lockowner
State . . . . . . . . . . . . . . . . . . . . . . . . . 281 State . . . . . . . . . . . . . . . . . . . . . . . . . 284
15.40. Operation 10044: ILLEGAL - Illegal operation . . . . . . 282 15.40. Operation 10044: ILLEGAL - Illegal operation . . . . . . 285
16. NFSv4 Callback Procedures . . . . . . . . . . . . . . . . . . 283 16. NFSv4 Callback Procedures . . . . . . . . . . . . . . . . . . 286
16.1. Procedure 0: CB_NULL - No Operation . . . . . . . . . . 283 16.1. Procedure 0: CB_NULL - No Operation . . . . . . . . . . 286
16.2. Procedure 1: CB_COMPOUND - Compound Operations . . . . . 283 16.2. Procedure 1: CB_COMPOUND - Compound Operations . . . . . 286
16.2.6. Operation 3: CB_GETATTR - Get Attributes . . . . . . 285 16.2.6. Operation 3: CB_GETATTR - Get Attributes . . . . . . 288
16.2.7. Operation 4: CB_RECALL - Recall an Open Delegation . 286 16.2.7. Operation 4: CB_RECALL - Recall an Open Delegation . 289
16.2.8. Operation 10044: CB_ILLEGAL - Illegal Callback 16.2.8. Operation 10044: CB_ILLEGAL - Illegal Callback
Operation . . . . . . . . . . . . . . . . . . . . . 287 Operation . . . . . . . . . . . . . . . . . . . . . 290
17. Security Considerations . . . . . . . . . . . . . . . . . . . 288 17. Security Considerations . . . . . . . . . . . . . . . . . . . 291
18. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 290 18. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 293
18.1. Named Attribute Definitions . . . . . . . . . . . . . . 290 18.1. Named Attribute Definitions . . . . . . . . . . . . . . 293
18.1.1. Initial Registry . . . . . . . . . . . . . . . . . . 291 18.1.1. Initial Registry . . . . . . . . . . . . . . . . . . 294
18.1.2. Updating Registrations . . . . . . . . . . . . . . . 291 18.1.2. Updating Registrations . . . . . . . . . . . . . . . 294
19. References . . . . . . . . . . . . . . . . . . . . . . . . . 291 19. References . . . . . . . . . . . . . . . . . . . . . . . . . 294
19.1. Normative References . . . . . . . . . . . . . . . . . . 291 19.1. Normative References . . . . . . . . . . . . . . . . . . 294
19.2. Informative References . . . . . . . . . . . . . . . . . 293 19.2. Informative References . . . . . . . . . . . . . . . . . 296
Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 295 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 299
Appendix B. RFC Editor Notes . . . . . . . . . . . . . . . . . . 296 Appendix B. RFC Editor Notes . . . . . . . . . . . . . . . . . . 300
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 297 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 300
1. Introduction 1. Introduction
1.1. NFS Version 4 Goals 1.1. NFS Version 4 Goals
The Network Filesystem version 4 (NFSv4) protocol is a further The Network Filesystem version 4 (NFSv4) protocol is a further
revision of the NFS protocol defined already by versions 2 [RFC1094] revision of the NFS protocol defined already by versions 2 [RFC1094]
and 3 [RFC1813]. It retains the essential characteristics of and 3 [RFC1813]. It retains the essential characteristics of
previous versions: design for easy recovery, independent of transport previous versions: design for easy recovery, independent of transport
protocols, operating systems and file systems, simplicity, and good protocols, operating systems and file systems, simplicity, and good
skipping to change at page 12, line 13 skipping to change at page 12, line 18
instance becomes unavailable. instance becomes unavailable.
o Location attributes may be provided when a previously present file o Location attributes may be provided when a previously present file
system becomes absent. This allows non-disruptive migration of system becomes absent. This allows non-disruptive migration of
file systems to alternative servers. file systems to alternative servers.
1.3.4. OPEN and CLOSE 1.3.4. OPEN and CLOSE
The NFSv4 protocol introduces OPEN and CLOSE operations. The OPEN The NFSv4 protocol introduces OPEN and CLOSE operations. The OPEN
operation provides a single point where file lookup, creation, and operation provides a single point where file lookup, creation, and
share semantics can be combined. The CLOSE operation also provides share semantics (see Section 9.9) can be combined. The CLOSE
for the release of state accumulated by OPEN. operation also provides for the release of state accumulated by OPEN.
1.3.5. File Locking 1.3.5. File Locking
With the NFSv4 protocol, the support for byte range file locking is With the NFSv4 protocol, the support for byte range file locking is
part of the NFS protocol. The file locking support is structured so part of the NFS protocol. The file locking support is structured so
that an RPC callback mechanism is not required. This is a departure that an RPC callback mechanism is not required. This is a departure
from the previous versions of the NFS file locking protocol, Network from the previous versions of the NFS file locking protocol, Network
Lock Manager (NLM) [RFC1813]. The state associated with file locks Lock Manager (NLM) [RFC1813]. The state associated with file locks
is maintained at the server under a lease-based model. The server is maintained at the server under a lease-based model. The server
defines a single lease period for all state held by a NFS client. If defines a single lease period for all state held by a NFS client. If
skipping to change at page 12, line 52 skipping to change at page 13, line 10
file is closed, any modified data is written to the server. file is closed, any modified data is written to the server.
If an application wants to serialize access to file data, file If an application wants to serialize access to file data, file
locking of the file data ranges in question should be used. locking of the file data ranges in question should be used.
The major addition to NFSv4 in the area of caching is the ability of The major addition to NFSv4 in the area of caching is the ability of
the server to delegate certain responsibilities to the client. When the server to delegate certain responsibilities to the client. When
the server grants a delegation for a file to a client, the client is the server grants a delegation for a file to a client, the client is
guaranteed certain semantics with respect to the sharing of that file guaranteed certain semantics with respect to the sharing of that file
with other clients. At OPEN, the server may provide the client with other clients. At OPEN, the server may provide the client
either a OPEN_DELEGATE_READ or OPEN_DELEGATE_WRITE delegation for the either a read (OPEN_DELEGATE_READ) or a write (OPEN_DELEGATE_WRITE)
file. If the client is granted a OPEN_DELEGATE_READ delegation, it delegation for the file (see Section 10.4). If the client is granted
is assured that no other client has the ability to write to the file a OPEN_DELEGATE_READ delegation, it is assured that no other client
for the duration of the delegation. If the client is granted a has the ability to write to the file for the duration of the
OPEN_DELEGATE_WRITE delegation, the client is assured that no other delegation. If the client is granted a OPEN_DELEGATE_WRITE
client has read or write access to the file. delegation, the client is assured that no other client has read or
write access to the file.
Delegations can be recalled by the server. If another client Delegations can be recalled by the server. If another client
requests access to the file in such a way that the access conflicts requests access to the file in such a way that the access conflicts
with the granted delegation, the server is able to notify the initial with the granted delegation, the server is able to notify the initial
client and recall the delegation. This requires that a callback path client and recall the delegation. This requires that a callback path
exist between the server and client. If this callback path does not exist between the server and client. If this callback path does not
exist, then delegations cannot be granted. The essence of a exist, then delegations cannot be granted. The essence of a
delegation is that it allows the client to locally service operations delegation is that it allows the client to locally service operations
such as OPEN, CLOSE, LOCK, LOCKU, READ, or WRITE without immediate such as OPEN, CLOSE, LOCK, LOCKU, READ, or WRITE without immediate
interaction with the server. interaction with the server.
1.4. General Definitions 1.4. General Definitions
The following definitions are provided for the purpose of providing The following definitions are provided for the purpose of providing
an appropriate context for the reader. an appropriate context for the reader.
Anonymous Stateid: Special locking object defined in
Section 9.1.4.3.
Absent File System: A file system is "absent" when a namespace Absent File System: A file system is "absent" when a namespace
component does not have a backing file system. component does not have a backing file system.
Byte: In this document, a byte is an octet, i.e., a datum exactly 8 Byte: In this document, a byte is an octet, i.e., a datum exactly 8
bits in length. bits in length.
Client: The client is the entity that accesses the NFS server's Client: The client is the entity that accesses the NFS server's
resources. The client may be an application that contains the resources. The client may be an application that contains the
logic to access the NFS server directly. The client may also be logic to access the NFS server directly. The client may also be
the traditional operating system client that provides remote file the traditional operating system client that provides remote file
skipping to change at page 14, line 11 skipping to change at page 14, line 22
File System: The file system is the collection of objects on a File System: The file system is the collection of objects on a
server that share the same fsid attribute (see Section 5.8.1.9). server that share the same fsid attribute (see Section 5.8.1.9).
Lease: An interval of time defined by the server for which the Lease: An interval of time defined by the server for which the
client is irrevocably granted a lock. At the end of a lease client is irrevocably granted a lock. At the end of a lease
period the lock may be revoked if the lease has not been extended. period the lock may be revoked if the lease has not been extended.
The lock must be revoked if a conflicting lock has been granted The lock must be revoked if a conflicting lock has been granted
after the lease interval. after the lease interval.
All leases granted by a server have the same fixed interval. Note All leases granted by a server have the same fixed duration. Note
that the fixed interval was chosen to alleviate the expense a that the fixed interval duration was chosen to alleviate the
server would have in maintaining state about variable length expense a server would have in maintaining state about variable
leases across server failures. length leases across server failures.
Lock: The term "lock" is used to refer to both record (byte-range) Lock: The term "lock" is used to refer to both record (byte-range)
locks as well as share reservations unless specifically stated locks as well as share reservations unless specifically stated
otherwise. otherwise.
Lock-Owner: Each byte-range lock is associated with a specific lock-
owner and an open-owner. The lock-owner consists of a Client ID
and an opaque owner string. The client presents this to the
server to establish the ownership of the byte-range lock as
needed.
Open-Owner: Each open file is associated with a specific open-owner,
which consists of a Client ID and an opaque owner string. The
client presents this to the server to establish the ownership of
the open as needed.
READ Bypass Stateid: Special locking object defined in
Section 9.1.4.3.
Server: The "Server" is the entity responsible for coordinating Server: The "Server" is the entity responsible for coordinating
client access to a set of file systems. client access to a set of file systems.
Stable Storage: NFSv4 servers must be able to recover without data Stable Storage: NFSv4 servers must be able to recover without data
loss from multiple power failures (including cascading power loss from multiple power failures (including cascading power
failures, that is, several power failures in quick succession), failures, that is, several power failures in quick succession),
operating system failures, and hardware failure of components operating system failures, and hardware failure of components
other than the storage medium itself (for example, disk, other than the storage medium itself (for example, disk,
nonvolatile RAM). nonvolatile RAM).
skipping to change at page 15, line 39 skipping to change at page 16, line 16
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. o The definition of stateid was strengthened.
1.6. Changes between RFC 3010 and RFC3530 1.6. Changes between RFC 3010 and RFC3530
The definition of the NFSv4 protocol in [RFC3530] replaced and The definition of the NFSv4 protocol in [RFC3530] replaced and
obsoleted the definition present in [RFC3010] While portions of the obsoleted the definition present in [RFC3010]. While portions of the
two documents remained the same, there were substantive changes in two documents remained the same, there were substantive changes in
others. The changes made between [RFC3010] and [RFC3530] reflect others. The changes made between [RFC3010] and [RFC3530] reflect
implementation experience and further review of the protocol. implementation experience and further review of the protocol.
The following list is not all inclusive of all changes but presents The following list is not 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
done to accommodate Posix based clients and the model they use for done to accommodate Posix based clients and the model they use for
file locking. For Posix clients, an open_owner4 would correspond file locking. For Posix clients, an open_owner4 would correspond
skipping to change at page 16, line 42 skipping to change at page 17, line 19
o Remove use of the pathname4 data type from LOOKUP and OPEN in o Remove use of the pathname4 data type from LOOKUP and OPEN in
favor of having the client construct a sequence of LOOKUP favor of having the client construct a sequence of LOOKUP
operations to achieve the same effect. operations to achieve the same effect.
2. Protocol Data Types 2. Protocol Data Types
The syntax and semantics to describe the data types of the NFS The syntax and semantics to describe the data types of the NFS
version 4 protocol are defined in the XDR [RFC4506] and RPC [RFC5531] version 4 protocol are defined in the XDR [RFC4506] and RPC [RFC5531]
documents. The next sections build upon the XDR data types to define documents. The next sections build upon the XDR data types to define
types and structures specific to this protocol. types and structures specific to this protocol. As a reminder, the
size constants and definitive definitions can be found in
[RFCNFSv4XDR].
2.1. Basic Data Types 2.1. Basic Data Types
These are the base NFSv4 data types. These are the base NFSv4 data types.
+-----------------+-------------------------------------------------+ +-----------------+-------------------------------------------------+
| Data Type | Definition | | Data Type | Definition |
+-----------------+-------------------------------------------------+ +-----------------+-------------------------------------------------+
| int32_t | typedef int int32_t; | | int32_t | typedef int int32_t; |
| uint32_t | typedef unsigned int uint32_t; | | uint32_t | typedef unsigned int uint32_t; |
skipping to change at page 17, line 28 skipping to change at page 18, line 7
| mode4 | typedef uint32_t mode4; | | mode4 | typedef uint32_t mode4; |
| | Mode attribute data type. | | | Mode attribute data type. |
| nfs_cookie4 | typedef uint64_t nfs_cookie4; | | nfs_cookie4 | typedef uint64_t nfs_cookie4; |
| | Opaque cookie value for READDIR. | | | Opaque cookie value for READDIR. |
| nfs_fh4 | typedef opaque nfs_fh4<NFS4_FHSIZE>; | | nfs_fh4 | typedef opaque nfs_fh4<NFS4_FHSIZE>; |
| | Filehandle definition. | | | Filehandle definition. |
| nfs_ftype4 | enum nfs_ftype4; | | nfs_ftype4 | enum nfs_ftype4; |
| | Various defined file types. | | | Various defined file types. |
| nfsstat4 | enum nfsstat4; | | nfsstat4 | enum nfsstat4; |
| | Return value for operations. | | | Return value for operations. |
| nfs_lease4 | typedef uint32_t nfs_lease4; |
| | Duration of a lease in seconds. |
| offset4 | typedef uint64_t offset4; | | offset4 | typedef uint64_t offset4; |
| | Various offset designations (READ, WRITE, LOCK, | | | Various offset designations (READ, WRITE, LOCK, |
| | COMMIT). | | | COMMIT). |
| qop4 | typedef uint32_t qop4; | | qop4 | typedef uint32_t qop4; |
| | Quality of protection designation in SECINFO. | | | Quality of protection designation in SECINFO. |
| sec_oid4 | typedef opaque sec_oid4<>; | | sec_oid4 | typedef opaque sec_oid4<>; |
| | Security Object Identifier. The sec_oid4 data | | | Security Object Identifier. The sec_oid4 data |
| | type is not really opaque. Instead it contains | | | type is not really opaque. Instead it contains |
| | an ASN.1 OBJECT IDENTIFIER as used by GSS-API | | | an ASN.1 OBJECT IDENTIFIER as used by GSS-API |
| | in the mech_type argument to | | | in the mech_type argument to |
skipping to change at page 18, line 10 skipping to change at page 18, line 39
| utf8str_mixed | typedef utf8string utf8str_mixed; | | utf8str_mixed | typedef utf8string utf8str_mixed; |
| | UTF-8 strings with a case sensitive prefix and | | | UTF-8 strings with a case sensitive prefix and |
| | a case insensitive suffix. | | | a case insensitive suffix. |
| component4 | typedef utf8str_cs component4; | | component4 | typedef utf8str_cs component4; |
| | Represents pathname components. | | | Represents pathname components. |
| linktext4 | typedef opaque linktext4<>; | | linktext4 | typedef opaque linktext4<>; |
| | Symbolic link contents ("symbolic link" is | | | Symbolic link contents ("symbolic link" is |
| | defined in an Open Group [openg_symlink] | | | defined in an Open Group [openg_symlink] |
| | standard). | | | standard). |
| ascii_REQUIRED4 | typedef utf8string ascii_REQUIRED4; | | ascii_REQUIRED4 | typedef utf8string ascii_REQUIRED4; |
| | String MUST be sent as ASCII and thus is | | | String is sent as ASCII and thus is |
| | automatically UTF-8. | | | automatically UTF-8. |
| pathname4 | typedef component4 pathname4<>; | | pathname4 | typedef component4 pathname4<>; |
| | Represents path name for fs_locations. | | | Represents path name for fs_locations. |
| nfs_lockid4 | typedef uint64_t nfs_lockid4; | | nfs_lockid4 | typedef uint64_t nfs_lockid4; |
| verifier4 | typedef opaque verifier4[NFS4_VERIFIER_SIZE]; | | verifier4 | typedef opaque verifier4[NFS4_VERIFIER_SIZE]; |
| | Verifier used for various operations (COMMIT, | | | Verifier used for various operations (COMMIT, |
| | CREATE, OPEN, READDIR, WRITE) | | | CREATE, OPEN, READDIR, WRITE) |
| | NFS4_VERIFIER_SIZE is defined as 8. | | | NFS4_VERIFIER_SIZE is defined as 8. |
+-----------------+-------------------------------------------------+ +-----------------+-------------------------------------------------+
skipping to change at page 19, line 42 skipping to change at page 20, line 25
This data type represents additional information for the device file This data type represents additional information for the device file
types NF4CHR and NF4BLK. types NF4CHR and NF4BLK.
2.2.5. fsid4 2.2.5. fsid4
struct fsid4 { struct fsid4 {
uint64_t major; uint64_t major;
uint64_t minor; uint64_t minor;
}; };
This type is the file system identifier that is used as a mandatory This type is the file system identifier that is used as a REQUIRED
attribute. attribute.
2.2.6. fs_location4 2.2.6. fs_location4
struct fs_location4 { struct fs_location4 {
utf8str_cis server<>; utf8str_cis server<>;
pathname4 rootpath; pathname4 rootpath;
}; };
2.2.7. fs_locations4 2.2.7. fs_locations4
struct fs_locations4 { struct fs_locations4 {
pathname4 fs_root; pathname4 fs_root;
fs_location4 locations<>; fs_location4 locations<>;
}; };
The fs_location4 and fs_locations4 data types are used for the The fs_location4 and fs_locations4 data types are used for the
fs_locations recommended attribute which is used for migration and fs_locations RECOMMENDED attribute which is used for migration and
replication support. replication support.
2.2.8. fattr4 2.2.8. fattr4
struct fattr4 { struct fattr4 {
bitmap4 attrmask; bitmap4 attrmask;
attrlist4 attr_vals; attrlist4 attr_vals;
}; };
The fattr4 structure is used to represent file and directory The fattr4 structure is used to represent file and directory
attributes. attributes.
The bitmap is a counted array of 32 bit integers used to contain bit The bitmap is a counted array of 32 bit integers used to contain bit
values. The position of the integer in the array that contains bit n values. The position of the integer in the array that contains bit n
can be computed from the expression (n / 32) and its bit within that can be computed from the expression (n / 32) and its bit within that
integer is (n mod 32). integer is (n mod 32).
0 1 0 1
+-----------+-----------+-----------+-- +-----------+-----------+-----------+--
skipping to change at page 21, line 4 skipping to change at page 21, line 30
bool atomic; bool atomic;
changeid4 before; changeid4 before;
changeid4 after; changeid4 after;
}; };
This structure is used with the CREATE, LINK, REMOVE, RENAME This structure is used with the CREATE, LINK, REMOVE, RENAME
operations to let the client know the value of the change attribute operations to let the client know the value of the change attribute
for the directory in which the target file system object resides. for the directory in which the target file system object resides.
2.2.10. clientaddr4 2.2.10. clientaddr4
struct clientaddr4 { struct clientaddr4 {
/* see struct rpcb in RFC 1833 */ /* see struct rpcb in RFC 1833 */
string r_netid<>; /* network id */ string r_netid<>; /* network id */
string r_addr<>; /* universal address */ string r_addr<>; /* universal address */
}; };
The clientaddr4 structure is used as part of the SETCLIENTID The clientaddr4 structure is used as part of the SETCLIENTID
operation to either specify the address of the client that is using a operation to either specify the address of the client that is using a
client ID or as part of the callback registration. The r_netid and client ID or as part of the callback registration. The r_netid and
r_addr fields respectively contain a netid and uaddr. The netid and r_addr fields respectively contain a network id and universal
uaddr concepts are defined in [RFC5665]. The netid and uaddr formats address. The network id and universal address concepts together with
for TCP over IPv4 and TCP over IPv6 are defined in [RFC5665], formats for TCP over IPv4 and TCP over IPv6 are defined in [RFC5665],
specifically Tables 2 and 3 and Sections 5.2.3.3 and 5.2.3.4. specifically Tables 2 and 3 and Sections 5.2.3.3 and 5.2.3.4.
2.2.11. cb_client4 2.2.11. cb_client4
struct cb_client4 { struct cb_client4 {
unsigned int cb_program; unsigned int cb_program;
clientaddr4 cb_location; clientaddr4 cb_location;
}; };
This structure is used by the client to inform the server of its call This structure is used by the client to inform the server of its call
back address; includes the program number and client address. back address; includes the program number and client address.
2.2.12. nfs_client_id4 2.2.12. nfs_client_id4
struct nfs_client_id4 { struct nfs_client_id4 {
verifier4 verifier; verifier4 verifier;
opaque id<NFS4_OPAQUE_LIMIT>; opaque id<NFS4_OPAQUE_LIMIT>;
}; };
skipping to change at page 24, line 50 skipping to change at page 25, line 37
configuration to map QOP zero to an appropriate level of protection. configuration to map QOP zero to an appropriate level of protection.
Each mandated mechanism specifies a minimum set of cryptographic Each mandated mechanism specifies a minimum set of cryptographic
algorithms for implementing integrity and privacy. NFSv4 clients and algorithms for implementing integrity and privacy. NFSv4 clients and
servers MUST be implemented on operating environments that comply servers MUST be implemented on operating environments that comply
with the required cryptographic algorithms of each required with the required cryptographic algorithms of each required
mechanism. mechanism.
3.2.1.1. Kerberos V5 as a Security Triple 3.2.1.1. Kerberos V5 as a Security Triple
The Kerberos V5 GSS-API mechanism as described in [RFC4121] MUST be The Kerberos V5 GSS-API mechanism as described in [RFC4121] MUST be
implemented with the RPCSEC_GSS services as specified in the implemented with the RPCSEC_GSS services as specified in Table 2.
following table: Both client and server MUST support each of the pseudo flavors.
column descriptions: Mapping pseudo flavor to service
1 == number of pseudo flavor
2 == name of pseudo flavor
3 == mechanism's OID
4 == RPCSEC_GSS service
5 == NFSv4 clients MUST support
6 == NFSv4 servers MUST support
1 2 3 4 5 6 +--------+-------+----------------------+-----------------------+
------------------------------------------------------------------ | Number | Name | Mechanism's OID | RPCSEC_GSS service |
390003 krb5 1.2.840.113554.1.2.2 rpc_gss_svc_none yes yes +--------+-------+----------------------+-----------------------+
390004 krb5i 1.2.840.113554.1.2.2 rpc_gss_svc_integrity yes yes | 390003 | krb5 | 1.2.840.113554.1.2.2 | rpc_gss_svc_none |
390005 krb5p 1.2.840.113554.1.2.2 rpc_gss_svc_privacy no yes | 390004 | krb5i | 1.2.840.113554.1.2.2 | rpc_gss_svc_integrity |
| 390005 | krb5p | 1.2.840.113554.1.2.2 | rpc_gss_svc_privacy |
+--------+-------+----------------------+-----------------------+
Table 2
Note that the pseudo flavor is presented here as a mapping aid to the Note that the pseudo flavor is presented here as a mapping aid to the
implementer. Because this NFS protocol includes a method to implementer. Because this NFS protocol includes a method to
negotiate security and it understands the GSS-API mechanism, the negotiate security and it understands the GSS-API mechanism, the
pseudo flavor is not needed. The pseudo flavor is needed for NFSv3 pseudo flavor is not needed. The pseudo flavor is needed for NFSv3
since the security negotiation is done via the MOUNT protocol as since the security negotiation is done via the MOUNT protocol as
described in [RFC2623]. described in [RFC2623].
At the time this document was specified, the Advanced Encryption At the time this document was specified, the Advanced Encryption
Standard (AES) with HMAC-SHA1 was a required algorithm set for Standard (AES) with HMAC-SHA1 was a required algorithm set for
skipping to change at page 26, line 17 skipping to change at page 27, line 7
different or multiple security mechanisms in use. different or multiple security mechanisms in use.
The security negotiation between client and server SHOULD be done The security negotiation between client and server SHOULD be done
with a secure channel to eliminate the possibility of a third party with a secure channel to eliminate the possibility of a third party
intercepting the negotiation sequence and forcing the client and intercepting the negotiation sequence and forcing the client and
server to choose a lower level of security than required or desired. server to choose a lower level of security than required or desired.
See Section 17 for further discussion. See Section 17 for further discussion.
3.3.1. SECINFO 3.3.1. SECINFO
The new SECINFO operation will allow the client to determine, on a The SECINFO operation will allow the client to determine, on a per
per filehandle basis, what security triple (see [RFC2743]) is to be filehandle basis, what security triple (see [RFC2743]) is to be used
used for server access. In general, the client will not have to use for server access. In general, the client will not have to use the
the SECINFO operation except during initial communication with the SECINFO operation except during initial communication with the server
server or when the client crosses policy boundaries at the server. or when the client encounters a new security policy as the client
It is possible that the server's policies change during the client's navigates the name space. Either condition will force the client to
interaction therefore forcing the client to negotiate a new security negotiate a new security triple.
triple.
3.3.2. Security Error 3.3.2. Security Error
Based on the assumption that each NFSv4 client and server MUST Based on the assumption that each NFSv4 client and server MUST
support a minimum set of security (i.e., Kerberos-V5 under support a minimum set of security (i.e., Kerberos-V5 under
RPCSEC_GSS), the NFS client will start its communication with the RPCSEC_GSS), the NFS client will start its communication with the
server with one of the minimal security triples. During server with one of the minimal security triples. During
communication with the server, the client can receive an NFS error of communication with the server, the client can receive an NFS error of
NFS4ERR_WRONGSEC. This error allows the server to notify the client NFS4ERR_WRONGSEC. This error allows the server to notify the client
that the security triple currently being used is not appropriate for that the security triple currently being used is not appropriate for
skipping to change at page 26, line 46 skipping to change at page 27, line 35
responsible for determining what security triples are available at responsible for determining what security triples are available at
the server and choose one which is appropriate for the client. See the server and choose one which is appropriate for the client. See
Section 15.33 for further discussion of how the client will respond Section 15.33 for further discussion of how the client will respond
to the NFS4ERR_WRONGSEC error and use SECINFO. to the NFS4ERR_WRONGSEC error and use SECINFO.
3.3.3. Callback RPC Authentication 3.3.3. Callback RPC Authentication
Except as noted elsewhere in this section, the callback RPC Except as noted elsewhere in this section, the callback RPC
(described later) MUST mutually authenticate the NFS server to the (described later) MUST mutually authenticate the NFS server to the
principal that acquired the client ID (also described later), using principal that acquired the client ID (also described later), using
the security flavor the original SETCLIENTID operation used. the security flavor of the original SETCLIENTID operation used.
For AUTH_NONE, there are no principals, so this is a non-issue. For AUTH_NONE, there are no principals, so this is a non-issue.
AUTH_SYS has no notions of mutual authentication or a server AUTH_SYS has no notions of mutual authentication or a server
principal, so the callback from the server simply uses the AUTH_SYS principal, so the callback from the server simply uses the AUTH_SYS
credential that the user used when he set up the delegation. credential that the user used when he set up the delegation.
For AUTH_DH, one commonly used convention is that the server uses the For AUTH_DH, one commonly used convention is that the server uses the
credential corresponding to this AUTH_DH principal: credential corresponding to this AUTH_DH principal:
skipping to change at page 29, line 9 skipping to change at page 29, line 41
However, it is up to the administrative software at the server and However, it is up to the administrative software at the server and
the policies of the server administrator to define the binding of the the policies of the server administrator to define the binding of the
PUBLIC filehandle and server file system object. The client may not PUBLIC filehandle and server file system object. The client may not
make any assumptions about this binding. The client uses the PUBLIC make any assumptions about this binding. The client uses the PUBLIC
filehandle via the PUTPUBFH operation. filehandle via the PUTPUBFH operation.
4.2. Filehandle Types 4.2. Filehandle Types
In the NFSv2 and NFSv3 protocols, there was one type of filehandle In the NFSv2 and NFSv3 protocols, there was one type of filehandle
with a single set of semantics, of which the primary one was that it with a single set of semantics, of which the primary one was that it
was peristent across a server reboot. As such, this type of was persistent across a server reboot. As such, this type of
filehandle is termed "persistent" in NFS Version 4. The semantics of filehandle is termed "persistent" in NFS Version 4. The semantics of
a persistent filehandle remain the same as before. A new type of a persistent filehandle remain the same as before. A new type of
filehandle introduced in NFS Version 4 is the "volatile" filehandle, filehandle introduced in NFS Version 4 is the "volatile" filehandle,
which attempts to accommodate certain server environments. which attempts to accommodate certain server environments.
The volatile filehandle type was introduced to address server The volatile filehandle type was introduced to address server
functionality or implementation issues which make correct functionality or implementation issues which make correct
implementation of a persistent filehandle infeasible. Some server implementation of a persistent filehandle infeasible. Some server
environments do not provide a file system level invariant that can be environments do not provide a file system level invariant that can be
used to construct a persistent filehandle. The underlying server used to construct a persistent filehandle. The underlying server
skipping to change at page 30, line 44 skipping to change at page 31, line 28
4.2.3. Volatile Filehandle 4.2.3. Volatile Filehandle
A volatile filehandle does not share the same longevity A volatile filehandle does not share the same longevity
characteristics of a persistent filehandle. The server may determine characteristics of a persistent filehandle. The server may determine
that a volatile filehandle is no longer valid at many different that a volatile filehandle is no longer valid at many different
points in time. If the server can definitively determine that a points in time. If the server can definitively determine that a
volatile filehandle refers to an object that has been removed, the volatile filehandle refers to an object that has been removed, the
server should return NFS4ERR_STALE to the client (as is the case for server should return NFS4ERR_STALE to the client (as is the case for
persistent filehandles). In all other cases where the server persistent filehandles). In all other cases where the server
determines that a volatile filehandle can no longer be used, it determines that a volatile filehandle can no longer be used, it
SHOULD return an error of NFS4ERR_FHEXPIRED. should return an error of NFS4ERR_FHEXPIRED.
The mandatory attribute "fh_expire_type" is used by the client to The REQUIRED attribute "fh_expire_type" is used by the client to
determine what type of filehandle the server is providing for a determine what type of filehandle the server is providing for a
particular file system. This attribute is a bitmask with the particular file system. This attribute is a bitmask with the
following values: following values:
FH4_PERSISTENT: The value of FH4_PERSISTENT is used to indicate a FH4_PERSISTENT: The value of FH4_PERSISTENT is used to indicate a
persistent filehandle, which is valid until the object is removed persistent filehandle, which is valid until the object is removed
from the file system. The server will not return from the file system. The server will not return
NFS4ERR_FHEXPIRED for this filehandle. FH4_PERSISTENT is defined NFS4ERR_FHEXPIRED for this filehandle. FH4_PERSISTENT is defined
as a value in which none of the bits specified below are set. as a value in which none of the bits specified below are set.
skipping to change at page 36, line 33 skipping to change at page 37, line 20
named attribute directories and ordinary directories is not named attribute directories and ordinary directories is not
allowed. allowed.
Names of attributes will not be controlled by this document or other Names of attributes will not be controlled by this document or other
IETF Standards Track documents. See Section 18 for further IETF Standards Track documents. See Section 18 for further
discussion. discussion.
5.4. Classification of Attributes 5.4. Classification of Attributes
Each of attributes accessed using SETATTR and GETATTR (i.e., REQUIRED Each of attributes accessed using SETATTR and GETATTR (i.e., REQUIRED
an RECOMMENDED attributes) can be can be classified in one of three an RECOMMENDED attributes) can be classified in one of three
categories: categories:
1. per server attributes for which the value of the attribute will 1. per server attributes for which the value of the attribute will
be the same for all file objects that share the same server. be the same for all file objects that share the same server.
2. per file system attributes for whch the value of the attribute 2. per file system attributes for which the value of the attribute
will be the same for some or all file objects that share the same will be the same for some or all file objects that share the same
server and fsid attribute (Section 5.8.1.9). See below for server and fsid attribute (Section 5.8.1.9). See below for
details regarding when such sharing is in effect. details regarding when such sharing is in effect.
3. per file system object attributes 3. per file system object attributes
The handling of per file system attributes depends on the particular The handling of per file system attributes depends on the particular
attribute and the setting of the homogeneous (Section 5.8.2.12) attribute and the setting of the homogeneous (Section 5.8.2.12)
attribute. The following rules apply: attribute. The following rules apply:
1. The values of the attribute supported_attrs, fsid, homgeneous, 1. The values of the attribute supported_attrs, fsid, homogeneous,
link_support, and symlink_support are always common to all object link_support, and symlink_support are always common to all object
within given file system. within the given file system.
2. For other attributes, different values may be returned for 2. For other attributes, different values may be returned for
different file system objects if the attribute homogeneous is different file system objects if the attribute homogeneous is
supported within the file system in question and has the value supported within the file system in question and has the value
false. false.
The classification of attributes is as follows. Note that the The classification of attributes is as follows. Note that the
attributes time_access_set and time_modify_set are not listed in this attributes time_access_set and time_modify_set are not listed in this
section because they are write-only attributes corresponding to section because they are write-only attributes corresponding to
time_access and time_modify, and are used in a special instance of time_access and time_modify, and are used in a special instance of
skipping to change at page 38, line 7 skipping to change at page 38, line 38
Some REQUIRED and RECOMMENDED attributes are set-only; i.e., they can Some REQUIRED and RECOMMENDED attributes are set-only; i.e., they can
be set via SETATTR but not retrieved via GETATTR. Similarly, some be set via SETATTR but not retrieved via GETATTR. Similarly, some
REQUIRED and RECOMMENDED attributes are get-only; i.e., they can be REQUIRED and RECOMMENDED attributes are get-only; i.e., they can be
retrieved via GETATTR but not set via SETATTR. If a client attempts retrieved via GETATTR but not set via SETATTR. If a client attempts
to set a get-only attribute or get a set-only attribute, the server to set a get-only attribute or get a set-only attribute, the server
MUST return NFS4ERR_INVAL. MUST return NFS4ERR_INVAL.
5.6. REQUIRED Attributes - List and Definition References 5.6. REQUIRED Attributes - List and Definition References
The list of REQUIRED attributes appears in Table 2. The meaning of The list of REQUIRED attributes appears in Table 3. The meaning of
the columns of the table are: the columns of the table are:
o Name: The name of attribute o Name: The name of attribute
o Id: The number assigned to the attribute. In the event of o Id: The number assigned to the attribute. In the event of
conflicts between the assigned number and [RFCNFSv4XDR], the conflicts between the assigned number and [RFCNFSv4XDR], the
latter is authoritative, but in such an event, it should be latter is authoritative, but in such an event, it should be
resolved with Errata to this document and/or [RFCNFSv4XDR]. See resolved with Errata to this document and/or [RFCNFSv4XDR]. See
[IESG_errata] for the Errata process. [IESG_ERRATA] for the Errata process.
o Data Type: The XDR data type of the attribute. o Data Type: The XDR data type of the attribute.
o Acc: Access allowed to the attribute. R means read-only (GETATTR o Acc: Access allowed to the attribute. R means read-only (GETATTR
may retrieve, SETATTR may not set). W means write-only (SETATTR may retrieve, SETATTR may not set). W means write-only (SETATTR
may set, GETATTR may not retrieve). R W means read/write (GETATTR may set, GETATTR may not retrieve). R W means read/write (GETATTR
may retrieve, SETATTR may set). may retrieve, SETATTR may set).
o Defined in: The section of this specification that describes the o Defined in: The section of this specification that describes the
attribute. attribute.
REQUIRED attributes
+-----------------+----+------------+-----+-------------------+ +-----------------+----+------------+-----+-------------------+
| Name | Id | Data Type | Acc | Defined in: | | Name | Id | Data Type | Acc | Defined in: |
+-----------------+----+------------+-----+-------------------+ +-----------------+----+------------+-----+-------------------+
| supported_attrs | 0 | bitmap4 | R | Section 5.8.1.1 | | supported_attrs | 0 | bitmap4 | R | Section 5.8.1.1 |
| type | 1 | nfs_ftype4 | R | Section 5.8.1.2 | | type | 1 | nfs_ftype4 | R | Section 5.8.1.2 |
| fh_expire_type | 2 | uint32_t | R | Section 5.8.1.3 | | fh_expire_type | 2 | uint32_t | R | Section 5.8.1.3 |
| change | 3 | uint64_t | R | Section 5.8.1.4 | | change | 3 | changeid4 | R | Section 5.8.1.4 |
| size | 4 | uint64_t | R W | Section 5.8.1.5 | | size | 4 | uint64_t | R W | Section 5.8.1.5 |
| link_support | 5 | bool | R | Section 5.8.1.6 | | link_support | 5 | bool | R | Section 5.8.1.6 |
| symlink_support | 6 | bool | R | Section 5.8.1.7 | | symlink_support | 6 | bool | R | Section 5.8.1.7 |
| named_attr | 7 | bool | R | Section 5.8.1.8 | | named_attr | 7 | bool | R | Section 5.8.1.8 |
| fsid | 8 | fsid4 | R | Section 5.8.1.9 | | fsid | 8 | fsid4 | R | Section 5.8.1.9 |
| unique_handles | 9 | bool | R | Section 5.8.1.10 | | unique_handles | 9 | bool | R | Section 5.8.1.10 |
| lease_time | 10 | nfs_lease4 | R | Section 5.8.1.11 | | lease_time | 10 | nfs_lease4 | R | Section 5.8.1.11 |
| rdattr_error | 11 | nfsstat4 | R | Section 5.8.1.12 | | rdattr_error | 11 | nfsstat4 | R | Section 5.8.1.12 |
| filehandle | 19 | nfs_fh4 | R | Section 5.8.1.13 | | filehandle | 19 | nfs_fh4 | R | Section 5.8.1.13 |
+-----------------+----+------------+-----+-------------------+ +-----------------+----+------------+-----+-------------------+
Table 2 Table 3
5.7. RECOMMENDED Attributes - List and Definition References 5.7. RECOMMENDED Attributes - List and Definition References
The RECOMMENDED attributes are defined in Table 3. The meanings of The RECOMMENDED attributes are defined in Table 4. The meanings of
the column headers are the same as Table 2; see Section 5.6 for the the column headers are the same as Table 3; see Section 5.6 for the
meanings. meanings.
RECOMMENDED attributes
+-------------------+----+-----------------+-----+------------------+ +-------------------+----+-----------------+-----+------------------+
| Name | Id | Data Type | Acc | Defined in: | | Name | Id | Data Type | Acc | Defined in: |
+-------------------+----+-----------------+-----+------------------+ +-------------------+----+-----------------+-----+------------------+
| acl | 12 | nfsace4<> | R W | Section 6.2.1 | | acl | 12 | nfsace4<> | R W | Section 6.2.1 |
| aclsupport | 13 | uint32_t | R | Section 6.2.1.2 | | aclsupport | 13 | uint32_t | R | Section 6.2.1.2 |
| archive | 14 | bool | R W | Section 5.8.2.1 | | archive | 14 | bool | R W | Section 5.8.2.1 |
| cansettime | 15 | bool | R | Section 5.8.2.2 | | cansettime | 15 | bool | R | Section 5.8.2.2 |
| case_insensitive | 16 | bool | R | Section 5.8.2.3 | | case_insensitive | 16 | bool | R | Section 5.8.2.3 |
| case_preserving | 17 | bool | R | Section 5.8.2.4 | | case_preserving | 17 | bool | R | Section 5.8.2.4 |
| chown_restricted | 18 | bool | R | Section 5.8.2.5 | | chown_restricted | 18 | bool | R | Section 5.8.2.5 |
| fileid | 20 | uint64_t | R | Section 5.8.2.6 | | fileid | 20 | uint64_t | R | Section 5.8.2.6 |
| files_avail | 21 | uint64_t | R | Section 5.8.2.7 | | files_avail | 21 | uint64_t | R | Section 5.8.2.7 |
| files_free | 22 | uint64_t | R | Section 5.8.2.8 | | files_free | 22 | uint64_t | R | Section 5.8.2.8 |
| files_total | 23 | uint64_t | R | Section 5.8.2.9 | | files_total | 23 | uint64_t | R | Section 5.8.2.9 |
| fs_locations | 24 | fs_locations | R | Section 5.8.2.10 | | fs_locations | 24 | fs_locations4 | R | Section 5.8.2.10 |
| hidden | 25 | bool | R W | Section 5.8.2.11 | | hidden | 25 | bool | R W | Section 5.8.2.11 |
| homogeneous | 26 | bool | R | Section 5.8.2.12 | | homogeneous | 26 | bool | R | Section 5.8.2.12 |
| maxfilesize | 27 | uint64_t | R | Section 5.8.2.13 | | maxfilesize | 27 | uint64_t | R | Section 5.8.2.13 |
| maxlink | 28 | uint32_t | R | Section 5.8.2.14 | | maxlink | 28 | uint32_t | R | Section 5.8.2.14 |
| maxname | 29 | uint32_t | R | Section 5.8.2.15 | | maxname | 29 | uint32_t | R | Section 5.8.2.15 |
| maxread | 30 | uint64_t | R | Section 5.8.2.16 | | maxread | 30 | uint64_t | R | Section 5.8.2.16 |
| maxwrite | 31 | uint64_t | R | Section 5.8.2.17 | | maxwrite | 31 | uint64_t | R | Section 5.8.2.17 |
| mimetype | 32 | ascii_ | R W | Section 5.8.2.18 | | mimetype | 32 | ascii_ | R W | Section 5.8.2.18 |
| | | REQUIRED4<> | | | | | | REQUIRED4<> | | |
| mode | 33 | mode4 | R W | Section 6.2.2 | | mode | 33 | mode4 | R W | Section 6.2.2 |
| mounted_on_fileid | 55 | uint64_t | R | Section 5.8.2.19 | | mounted_on_fileid | 55 | uint64_t | R | Section 5.8.2.19 |
| no_trunc | 34 | bool | R | Section 5.8.2.20 | | no_trunc | 34 | bool | R | Section 5.8.2.20 |
| numlinks | 35 | uint32_t | R | Section 5.8.2.21 | | numlinks | 35 | uint32_t | R | Section 5.8.2.21 |
| owner | 36 | utf8<> | R W | Section 5.8.2.22 | | owner | 36 | utf8str_mixed | R W | Section 5.8.2.22 |
| owner_group | 37 | utf8<> | R W | Section 5.8.2.23 | | owner_group | 37 | utf8str_mixed | R W | Section 5.8.2.23 |
| quota_avail_hard | 38 | uint64_t | R | Section 5.8.2.24 | | quota_avail_hard | 38 | uint64_t | R | Section 5.8.2.24 |
| quota_avail_soft | 39 | uint64_t | R | Section 5.8.2.25 | | quota_avail_soft | 39 | uint64_t | R | Section 5.8.2.25 |
| quota_used | 40 | uint64_t | R | Section 5.8.2.26 | | quota_used | 40 | uint64_t | R | Section 5.8.2.26 |
| rawdev | 41 | specdata4 | R | Section 5.8.2.27 | | rawdev | 41 | specdata4 | R | Section 5.8.2.27 |
| space_avail | 42 | uint64_t | R | Section 5.8.2.28 | | space_avail | 42 | uint64_t | R | Section 5.8.2.28 |
| space_free | 43 | uint64_t | R | Section 5.8.2.29 | | space_free | 43 | uint64_t | R | Section 5.8.2.29 |
| space_total | 44 | uint64_t | R | Section 5.8.2.30 | | space_total | 44 | uint64_t | R | Section 5.8.2.30 |
| space_used | 45 | uint64_t | R | Section 5.8.2.31 | | space_used | 45 | uint64_t | R | Section 5.8.2.31 |
| system | 46 | bool | R W | Section 5.8.2.32 | | system | 46 | bool | R W | Section 5.8.2.32 |
| time_access | 47 | nfstime4 | R | Section 5.8.2.33 | | time_access | 47 | nfstime4 | R | Section 5.8.2.33 |
| time_access_set | 48 | settime4 | W | Section 5.8.2.34 | | time_access_set | 48 | settime4 | W | Section 5.8.2.34 |
| time_backup | 49 | nfstime4 | R W | Section 5.8.2.35 | | time_backup | 49 | nfstime4 | R W | Section 5.8.2.35 |
| time_create | 50 | nfstime4 | R W | Section 5.8.2.36 | | time_create | 50 | nfstime4 | R W | Section 5.8.2.36 |
| time_delta | 51 | nfstime4 | R | Section 5.8.2.37 | | time_delta | 51 | nfstime4 | R | Section 5.8.2.37 |
| time_metadata | 52 | nfstime4 | R | Section 5.8.2.38 | | time_metadata | 52 | nfstime4 | R | Section 5.8.2.38 |
| time_modify | 53 | nfstime4 | R | Section 5.8.2.39 | | time_modify | 53 | nfstime4 | R | Section 5.8.2.39 |
| time_modify_set | 54 | settime4 | W | Section 5.8.2.40 | | time_modify_set | 54 | settime4 | W | Section 5.8.2.40 |
+-------------------+----+-----------------+-----+------------------+ +-------------------+----+-----------------+-----+------------------+
Table 3 Table 4
5.8. Attribute Definitions 5.8. Attribute Definitions
5.8.1. Definitions of REQUIRED Attributes 5.8.1. Definitions of REQUIRED Attributes
5.8.1.1. Attribute 0: supported_attrs 5.8.1.1. Attribute 0: supported_attrs
The bit vector that would retrieve all REQUIRED and RECOMMENDED The bit vector that would retrieve all REQUIRED and RECOMMENDED
attributes that are supported for this object. The scope of this attributes that are supported for this object. The scope of this
attribute applies to all objects with a matching fsid. attribute applies to all objects with a matching fsid.
skipping to change at page 43, line 48 skipping to change at page 44, line 48
TRUE, if this object's file system is homogeneous, i.e., all objects TRUE, if this object's file system is homogeneous, i.e., all objects
in the file system (all objects on the server with the same fsid) in the file system (all objects on the server with the same fsid)
have common values for all per-file-system attributes. have common values for all per-file-system attributes.
5.8.2.13. Attribute 27: maxfilesize 5.8.2.13. Attribute 27: maxfilesize
Maximum supported file size for the file system of this object. Maximum supported file size for the file system of this object.
5.8.2.14. Attribute 28: maxlink 5.8.2.14. Attribute 28: maxlink
Maximum number of links for this object. Maximum number of hard links for this object.
5.8.2.15. Attribute 29: maxname 5.8.2.15. Attribute 29: maxname
Maximum file name size supported for this object. Maximum file name size supported for this object.
5.8.2.16. Attribute 30: maxread 5.8.2.16. Attribute 30: maxread
Maximum amount of data the READ operation will return for this Maximum amount of data the READ operation will return for this
object. object.
skipping to change at page 49, line 49 skipping to change at page 50, line 49
The "dns_domain" portion of the owner string is meant to be a DNS The "dns_domain" portion of the owner string is meant to be a DNS
domain name. For example, "user@example.org". Servers should accept domain name. For example, "user@example.org". Servers should accept
as valid a set of users for at least one domain. A server may treat as valid a set of users for at least one domain. A server may treat
other domains as having no valid translations. A more general other domains as having no valid translations. A more general
service is provided when a server is capable of accepting users for service is provided when a server is capable of accepting users for
multiple domains, or for all domains, subject to security multiple domains, or for all domains, subject to security
constraints. constraints.
As an implementation guide, both clients and servers may provide a As an implementation guide, both clients and servers may provide a
means to configure the "dns_domain" portion of the owner string. For means to configure the "dns_domain" portion of the owner string. For
example, the DNS domain name might be "lab.example.org", but the user example, the DNS domain name of the host running the NFS server might
names are defined in "example.org". In the absence of such a be "lab.example.org", but the user names are defined in
configuration, or as a default, the current DNS domain name of the "example.org". In the absence of such a configuration, or as a
server should be the value used for the "dns_domain". default, the current DNS domain name of the server should be the
value used for the "dns_domain".
As mentioned above, it is desirable that a server when accepting a As mentioned above, it is desirable that a server when accepting a
string of the form "user@domain" or "group@domain" in an attribute, string of the form "user@domain" or "group@domain" in an attribute,
return this same string when that corresponding attribute is fetched. return this same string when that corresponding attribute is fetched.
Internationalization issues (for a general discussion of which see Internationalization issues make this impossible under certain
Section 12) may make this impossible and the client needs to take circumstances and the client needs to take note of these. See
note of the following situations: Section 12 for a detailed discussion of these issues.
o The string representing the domain may be converted to an
equivalent U-label (see [RFC5890]), if presented using a form
other than a U-label. See Section 12.6 for details.
o The user or group may be returned or used for verification in a
different form, as a result of Unicode normalization at the
server. The result SHOULD be a canonically equivalent Unicode
string [UNICODE]. Other sorts of string modification, including
case mapping or folding, SHOULD NOT be done as such modifications
may cause the server to merge identities that are separate at the
client.
In the case where there is no translation available to the client or In the case where there is no translation available to the client or
server, the attribute value will be constructed without the "@". server, the attribute value will be constructed without the "@".
Therefore, the absence of the "@" from the owner or owner_group Therefore, the absence of the "@" from the owner or owner_group
attribute signifies that no translation was available at the sender attribute signifies that no translation was available at the sender
and that the receiver of the attribute should not use that string as and that the receiver of the attribute should not use that string as
a basis for translation into its own internal format. Even though a basis for translation into its own internal format. Even though
the attribute value cannot be translated, it may still be useful. In the attribute value cannot be translated, it may still be useful. In
the case of a client, the attribute string may be used for local the case of a client, the attribute string may be used for local
display of ownership. display of ownership.
skipping to change at page 50, line 46 skipping to change at page 51, line 34
To provide a greater degree of compatibility with NFSv3, which To provide a greater degree of compatibility with NFSv3, which
identified users and groups by 32-bit unsigned user identifiers and identified users and groups by 32-bit unsigned user identifiers and
group identifiers, owner and group strings that consist of ASCII- group identifiers, owner and group strings that consist of ASCII-
encoded decimal numeric values with no leading zeros can be given a encoded decimal numeric values with no leading zeros can be given a
special interpretation by clients and servers that choose to provide special interpretation by clients and servers that choose to provide
such support. The receiver may treat such a user or group string as such support. The receiver may treat such a user or group string as
representing the same user as would be represented by an NFSv3 uid or representing the same user as would be represented by an NFSv3 uid or
gid having the corresponding numeric value. gid having the corresponding numeric value.
A server SHOULD reject such a numeric value if the security mechanism A server SHOULD reject such a numeric value if the security mechanism
is kerberized. I.e., in such a scenario, the client will already is using Kerberos. I.e., in such a scenario, the client will already
need to form "user@domain" strings. For any other security need to form "user@domain" strings. For any other security
mechanism, the server SHOULD accept such numeric values. As an mechanism, the server SHOULD accept such numeric values. As an
implementation note, the server could make such an acceptance be implementation note, the server could make such an acceptance be
configurable. If the server does not support numeric values or if it configurable. If the server does not support numeric values or if it
is configured off, then it MUST return an NFS4ERR_BADOWNER error. If is configured off, then it MUST return an NFS4ERR_BADOWNER error. If
the security mechanism is kerberized and the client attempts to use the security mechanism is using Kerberos and the client attempts to
the special form, then the server SHOULD return an NFS4ERR_BADOWNER use the special form, then the server SHOULD return an
error when there is a valid translation for the user or owner NFS4ERR_BADOWNER error when there is a valid translation for the user
designated in this way. In that case, the client must use the or owner designated in this way. In that case, the client must use
appropriate user@domain string and not the special form for the appropriate user@domain string and not the special form for
compatibility. compatibility.
The client MUST always accept numeric values if the security The client MUST always accept numeric values if the security
mechanism is not RPCSEC_GSS. A client can determine if a server mechanism is not RPCSEC_GSS. A client can determine if a server
supports numeric identifiers by first attempting to provide a numeric supports numeric identifiers by first attempting to provide a numeric
identifier. If this attempt rejected with an NFS4ERR_BADOWNER error, identifier. If this attempt rejected with an NFS4ERR_BADOWNER error,
then the client should only use named identifiers of the form then the client should only use named identifiers of the form
"user@dns_domain". "user@dns_domain".
The owner string "nobody" may be used to designate an anonymous user, The owner string "nobody" may be used to designate an anonymous user,
skipping to change at page 51, line 47 skipping to change at page 52, line 36
character without a dot, therefore in such languages, unless an I is character without a dot, therefore in such languages, unless an I is
before a dot_above, the "I" (U+0049) character should be case folded before a dot_above, the "I" (U+0049) character should be case folded
to a different character, LATIN SMALL LETTER DOTLESS I (U+0131). to a different character, LATIN SMALL LETTER DOTLESS I (U+0131).
The [UNICODE] and [SPECIALCASING] references in this RFC are for The [UNICODE] and [SPECIALCASING] references in this RFC are for
version 6.3.0 of the Unicode standard, as that was the latest version version 6.3.0 of the Unicode standard, as that was the latest version
of Unicode when this RFC was published. Implementations SHOULD of Unicode when this RFC was published. Implementations SHOULD
always use the latest version of Unicode (http://www.unicode.org/ always use the latest version of Unicode (http://www.unicode.org/
versions/latest/). versions/latest/).
[RFC Editor: please check that 6.3.0 is the latest version before
publication of this document as an RFC.]
6. Access Control Attributes 6. Access Control Attributes
Access Control Lists (ACLs) are file attributes that specify fine Access Control Lists (ACLs) are file attributes that specify fine
grained access control. This chapter covers the "acl", "aclsupport", grained access control. This chapter covers the "acl", "aclsupport",
"mode", file attributes, and their interactions. Note that file "mode", file attributes, and their interactions. Note that file
attributes may apply to any file system object. attributes may apply to any file system object.
6.1. Goals 6.1. Goals
ACLs and modes represent two well established models for specifying ACLs and modes represent two well established models for specifying
skipping to change at page 52, line 46 skipping to change at page 53, line 38
o When a mode attribute is set on an object, the ACL attributes may o When a mode attribute is set on an object, the ACL attributes may
need to be modified so as to not conflict with the new mode. In need to be modified so as to not conflict with the new mode. In
such cases, it is desirable that the ACL keep as much information such cases, it is desirable that the ACL keep as much information
as possible. This includes information about inheritance, AUDIT as possible. This includes information about inheritance, AUDIT
and ALARM ACEs, and permissions granted and denied that do not and ALARM ACEs, and permissions granted and denied that do not
conflict with the new mode. conflict with the new mode.
6.2. File Attributes Discussion 6.2. File Attributes Discussion
Support for each of the ACL attributes is RECOMMENED and not Support for each of the ACL attributes is RECOMMENDED and not
required, since file systems accessed using NFSV4 might not support required, since file systems accessed using NFSV4 might not support
ACL's. ACL's.
6.2.1. Attribute 12: acl 6.2.1. Attribute 12: acl
The NFSv4.0 ACL attribute contains an array of access control entries The NFSv4.0 ACL attribute contains an array of access control entries
(ACEs) that are associated with the file system object. Although the (ACEs) that are associated with the file system object. Although the
client can read and write the acl attribute, the server is client can read and write the acl attribute, the server is
responsible for using the ACL to perform access control. The client responsible for using the ACL to perform access control. The client
can use the OPEN or ACCESS operations to check access without can use the OPEN or ACCESS operations to check access without
skipping to change at page 54, line 23 skipping to change at page 55, line 12
style server might choose to silently allow read attribute style server might choose to silently allow read attribute
permissions even though an ACL does not explicitly allow those permissions even though an ACL does not explicitly allow those
permissions. (An ACL that explicitly denies permission to read permissions. (An ACL that explicitly denies permission to read
attributes should still result in a denial.) attributes should still result in a denial.)
The situation is complicated by the fact that a server may have The situation is complicated by the fact that a server may have
multiple modules that enforce ACLs. For example, the enforcement for multiple modules that enforce ACLs. For example, the enforcement for
NFSv4.0 access may be different from, but not weaker than, the NFSv4.0 access may be different from, but not weaker than, the
enforcement for local access, and both may be different from the enforcement for local access, and both may be different from the
enforcement for access through other protocols such as Server Message enforcement for access through other protocols such as Server Message
Block (SMB). So it may be useful for a server to accept an ACL even Block (SMB) [MS-SMB]. So it may be useful for a server to accept an
if not all of its modules are able to support it. ACL even if not all of its modules are able to support it.
The guiding principle with regard to NFSv4 access is that the server The guiding principle with regard to NFSv4 access is that the server
must not accept ACLs that give an appearance of more restricted must not accept ACLs that give an appearance of more restricted
access to a file than what is actually enforced. access to a file than what is actually enforced.
6.2.1.1. ACE Type 6.2.1.1. ACE Type
The constants used for the type field (acetype4) are as follows: The constants used for the type field (acetype4) are as follows:
const ACE4_ACCESS_ALLOWED_ACE_TYPE = 0x00000000; const ACE4_ACCESS_ALLOWED_ACE_TYPE = 0x00000000;
skipping to change at page 66, line 35 skipping to change at page 67, line 35
| EVERYONE | The world, including the owner and owning group. | | EVERYONE | The world, including the owner and owning group. |
| INTERACTIVE | Accessed from an interactive terminal. | | INTERACTIVE | Accessed from an interactive terminal. |
| NETWORK | Accessed via the network. | | NETWORK | Accessed via the network. |
| DIALUP | Accessed as a dialup user to the server. | | DIALUP | Accessed as a dialup user to the server. |
| BATCH | Accessed from a batch job. | | BATCH | Accessed from a batch job. |
| ANONYMOUS | Accessed without any authentication. | | ANONYMOUS | Accessed without any authentication. |
| AUTHENTICATED | Any authenticated user (opposite of ANONYMOUS). | | AUTHENTICATED | Any authenticated user (opposite of ANONYMOUS). |
| SERVICE | Access from a system service. | | SERVICE | Access from a system service. |
+---------------+---------------------------------------------------+ +---------------+---------------------------------------------------+
Table 4 Table 5
To avoid conflict, these special identifiers are distinguished by an To avoid conflict, these special identifiers are distinguished by an
appended "@" and should appear in the form "xxxx@" (with no domain appended "@" and should appear in the form "xxxx@" (with no domain
name after the "@"). For example: ANONYMOUS@. name after the "@"). For example: ANONYMOUS@.
The ACE4_IDENTIFIER_GROUP flag MUST be ignored on entries with these The ACE4_IDENTIFIER_GROUP flag MUST be ignored on entries with these
special identifiers. When encoding entries with these special special identifiers. When encoding entries with these special
identifiers, the ACE4_IDENTIFIER_GROUP flag SHOULD be set to zero. identifiers, the ACE4_IDENTIFIER_GROUP flag SHOULD be set to zero.
6.2.1.5.1. Discussion of EVERYONE@ 6.2.1.5.1. Discussion of EVERYONE@
skipping to change at page 68, line 38 skipping to change at page 69, line 38
Clients SHOULD NOT do their own access checks based on their Clients SHOULD NOT do their own access checks based on their
interpretation the ACL, but rather use the OPEN and ACCESS operations interpretation the ACL, but rather use the OPEN and ACCESS operations
to do access checks. This allows the client to act on the results of to do access checks. This allows the client to act on the results of
having the server determine whether or not access should be granted having the server determine whether or not access should be granted
based on its interpretation of the ACL. based on its interpretation of the ACL.
Clients must be aware of situations in which an object's ACL will Clients must be aware of situations in which an object's ACL will
define a certain access even though the server will not have adequate define a certain access even though the server will not have adequate
information to enforce it. For example, the server has no way of information to enforce it. For example, the server has no way of
determining whether a particular OPEN reflects a user's open for read determining whether a particular OPEN reflects a user's open for read
access, or is done as part of executing the file in question In such access, or is done as part of executing the file in question. In
situations, the client needs to do its part in the enforcement of such situations, the client needs to do its part in the enforcement
access as defined by the ACL. To do this, the client will send the of access as defined by the ACL. To do this, the client will send
appropriate ACCESS operation (or use a cached previous determination) the appropriate ACCESS operation (or use a cached previous
prior to servicing the request of the user or application in order to determination) prior to servicing the request of the user or
determine whether the user or application should be granted the application in order to determine whether the user or application
access requested. For examples in which the ACL may define accesses should be granted the access requested. For examples in which the
that the server does not enforce see Section 6.3.1.1. ACL may define accesses that the server does not enforce see
Section 6.3.1.1.
6.3.2. Computing a Mode Attribute from an ACL 6.3.2. Computing a Mode Attribute from an ACL
The following method can be used to calculate the MODE4_R*, MODE4_W* The following method can be used to calculate the MODE4_R*, MODE4_W*
and MODE4_X* bits of a mode attribute, based upon an ACL. and MODE4_X* bits of a mode attribute, based upon an ACL.
First, for each of the special identifiers OWNER@, GROUP@, and First, for each of the special identifiers OWNER@, GROUP@, and
EVERYONE@, evaluate the ACL in order, considering only ALLOW and DENY EVERYONE@, evaluate the ACL in order, considering only ALLOW and DENY
ACEs for the identifier EVERYONE@ and for the identifier under ACEs for the identifier EVERYONE@ and for the identifier under
consideration. The result of the evaluation will be an NFSv4 ACL consideration. The result of the evaluation will be an NFSv4 ACL
skipping to change at page 76, line 24 skipping to change at page 77, line 24
for the path "/a/b/c/d", the server's response is the filehandle of for the path "/a/b/c/d", the server's response is the filehandle of
the file system "/a/b/c/d". In previous versions of the NFS the file system "/a/b/c/d". In previous versions of the NFS
protocol, the server would respond with the filehandle of directory " protocol, the server would respond with the filehandle of directory "
/a/b/c/d" within the file system "/a/b". /a/b/c/d" within the file system "/a/b".
The NFS client will be able to determine if it crosses a server mount The NFS client will be able to determine if it crosses a server mount
point by a change in the value of the "fsid" attribute. point by a change in the value of the "fsid" attribute.
7.8. Security Policy and Name Space Presentation 7.8. Security Policy and Name Space Presentation
The application of the server's security policy needs to be carefully Because NFSv4 clients possess the ability to change the security
considered by the implementer. One may choose to limit the mechanisms used, after determining what is allowed, by using SECINFO
viewability of portions of the pseudo file system based on the the server SHOULD NOT present a different view of the namespace based
server's perception of the client's ability to authenticate itself on the security mechanism being used by a client. Instead, it should
properly. However, with the support of multiple security mechanisms present a consistent view and return NFS4ERR_WRONGSEC if an attempt
and the ability to negotiate the appropriate use of these mechanisms, is made to access data with an inappropriate security mechanism.
the server is unable to properly determine if a client will be able
to authenticate itself. If, based on its policies, the server
chooses to limit the contents of the pseudo file system, the server
may effectively hide file systems from a client that may otherwise
have legitimate access.
As suggested practice, the server should apply the security policy of If security considerations make it necessary to hide the existence of
a shared resource in the server's namespace to the components of the a particular file system, as opposed to all of the data within it,
resource's ancestors. For example: the server can apply the security policy of a shared resource in the
server's namespace to components of the resource's ancestors. For
example:
/ / (place holder/not exported)
/a/b /a/b (file system 1)
/a/b/c /a/b/MySecretProject (file system 2)
The /a/b/c directory is a real file system and is the shared The /a/b/MySecretProject directory is a real file system and is the
resource. The security policy for /a/b/c is Kerberos with integrity. shared resource. Suppose the security policy for /a/b/
The server should apply the same security policy to /, /a, and /a/b. MySecretProject is Kerberos with integrity and it is desired to limit
This allows for the extension of the protection of the server's knowledge of the existence of this file system. In this case, the
namespace to the ancestors of the real shared resource. server should apply the same security policy to /a/b. This allows
for knowledge of the existence of a file system to be secured when
desirable.
For the case of the use of multiple, disjoint security mechanisms in For the case of the use of multiple, disjoint security mechanisms in
the server's resources, the security for a particular object in the the server's resources, applying that sort of policy would result in
server's namespace should be the union of all security mechanisms of the higher-level file system not being accessible using any security
all direct descendants. flavor. Therefore, that sort of configuration is not compatible with
hiding the existence (as opposed to the contents) from clients using
multiple disjoint sets of security flavors.
In other circumstances, a desirable policy is for the security of a
particular object in the server's namespace to include the union of
all security mechanisms of all direct descendants. A common and
convenient practice, unless strong security requirements dictate
otherwise, is to make the entire pseudo file system accessible by all
of the valid security mechanisms.
Where there is concern about the security of data on the network,
clients should use strong security mechanisms to access the pseudo
file system in order to prevent man-in-the-middle attacks.
8. Multi-Server Namespace 8. Multi-Server Namespace
NFSv4 supports attributes that allow a namespace to extend beyond the NFSv4 supports attributes that allow a namespace to extend beyond the
boundaries of a single server. It is RECOMMENDED that clients and boundaries of a single server. It is RECOMMENDED that clients and
servers support construction of such multi-server namespaces. Use of servers support construction of such multi-server namespaces. Use of
such multi-server namespaces is OPTIONAL, however, and for many such multi-server namespaces is optional, however, and for many
purposes, single-server namespaces are perfectly acceptable. Use of purposes, single-server namespaces are perfectly acceptable. Use of
multi-server namespaces can provide many advantages, however, by multi-server namespaces can provide many advantages, however, by
separating a file system's logical position in a namespace from the separating a file system's logical position in a namespace from the
(possibly changing) logistical and administrative considerations that (possibly changing) logistical and administrative considerations that
result in particular file systems being located on particular result in particular file systems being located on particular
servers. servers.
8.1. Location Attributes 8.1. Location Attributes
NFSv4 contains RECOMMENDED attributes that allow file systems on one NFSv4 contains RECOMMENDED attributes that allow file systems on one
skipping to change at page 78, line 14 skipping to change at page 79, line 24
NFS4ERR_MOVED. Note that if the server ever returns the error NFS4ERR_MOVED. Note that if the server ever returns the error
NFS4ERR_MOVED, it MUST support the fs_locations attribute. NFS4ERR_MOVED, it MUST support the fs_locations attribute.
While the error name suggests that we have a case of a file system While the error name suggests that we have a case of a file system
that once was present, and has only become absent later, this is only that once was present, and has only become absent later, this is only
one possibility. A position in the namespace may be permanently one possibility. A position in the namespace may be permanently
absent with the set of file system(s) designated by the location absent with the set of file system(s) designated by the location
attributes being the only realization. The name NFS4ERR_MOVED attributes being the only realization. The name NFS4ERR_MOVED
reflects an earlier, more limited conception of its function, but reflects an earlier, more limited conception of its function, but
this error will be returned whenever the referenced file system is this error will be returned whenever the referenced file system is
absent, whether it has moved or not. absent, whether it has moved or simply never existed.
Except in the case of GETATTR-type operations (to be discussed Except in the case of GETATTR-type operations (to be discussed
later), when the current filehandle at the start of an operation is later), when the current filehandle at the start of an operation is
within an absent file system, that operation is not performed and the within an absent file system, that operation is not performed and the
error NFS4ERR_MOVED is returned, to indicate that the file system is error NFS4ERR_MOVED is returned, to indicate that the file system is
absent on the current server. absent on the current server.
Because a GETFH cannot succeed if the current filehandle is within an Because a GETFH cannot succeed if the current filehandle is within an
absent file system, filehandles within an absent file system cannot absent file system, filehandles within an absent file system cannot
be transferred to the client. When a client does have filehandles be transferred to the client. When a client does have filehandles
skipping to change at page 81, line 7 skipping to change at page 82, line 15
same data. same data.
When a file system is present and subsequently becomes absent, When a file system is present and subsequently becomes absent,
clients can be given the opportunity to have continued access to clients can be given the opportunity to have continued access to
their data, at an alternative location. Transfer of the file system their data, at an alternative location. Transfer of the file system
contents to the new location is referred to as "migration". See contents to the new location is referred to as "migration". See
Section 8.4.2 for details. Section 8.4.2 for details.
Alternative locations may be be physical replicas of the file system Alternative locations may be be physical replicas of the file system
data or alternative communication paths to the same server or, in the data or alternative communication paths to the same server or, in the
case of various foms of server clustering, another server providing case of various forms of server clustering, another server providing
access to the same physical file system. The client's access to the same physical file system. The client's
responsibilities in dealing with this transition depend on the responsibilities in dealing with this transition depend on the
specific nature of the new access path as well as how and whether specific nature of the new access path as well as how and whether
data was in fact migrated. These issues will be discussed in detail data was in fact migrated. These issues will be discussed in detail
below. below.
Where a file system was not previously present, specification of file Where a file system was not previously present, specification of file
system location provides a means by which file systems located on one system location provides a means by which file systems located on one
server can be associated with a namespace defined by another server, server can be associated with a namespace defined by another server,
thus allowing a general multi-server namespace facility. A thus allowing a general multi-server namespace facility. A
skipping to change at page 83, line 34 skipping to change at page 84, line 43
When multiple addresses for the same server exist, the client may When multiple addresses for the same server exist, the client may
assume that for each file system in the namespace of a given server assume that for each file system in the namespace of a given server
network address, there exist file systems at corresponding namespace network address, there exist file systems at corresponding namespace
locations for each of the other server network addresses. It may do locations for each of the other server network addresses. It may do
this even in the absence of explicit listing in fs_locations. Such this even in the absence of explicit listing in fs_locations. Such
corresponding file system locations can be used as alternative corresponding file system locations can be used as alternative
locations, just as those explicitly specified via the fs_locations locations, just as those explicitly specified via the fs_locations
attribute. attribute.
If a single location entry designates multiple server IP addresses, If a single location entry designates multiple server IP addresses,
the client cannot assume that these addresses are multiple paths to the client should choose a single one to use. When two server
the same server. In most cases, they will be, but the client MUST
verify that before acting on that assumption. When two server
addresses are designated by a single location entry and they addresses are designated by a single location entry and they
correspond to different servers, this normally indicates some sort of correspond to different servers, this normally indicates some sort of
misconfiguration, and so the client should avoid using such location misconfiguration, and so the client should avoid using such location
entries when alternatives are available. When they are not, clients entries when alternatives are available. When they are not, clients
should pick one of IP addresses and use it, without using others that should pick one of IP addresses and use it, without using others that
are not directed to the same server. are not directed to the same server.
8.6. Additional Client-Side Considerations 8.6. Additional Client-Side Considerations
When clients make use of servers that implement referrals, When clients make use of servers that implement referrals,
skipping to change at page 84, line 29 skipping to change at page 85, line 38
Another issue concerns refresh of referral locations. When referrals Another issue concerns refresh of referral locations. When referrals
are used extensively, they may change as server configurations are used extensively, they may change as server configurations
change. It is expected that clients will cache information related change. It is expected that clients will cache information related
to traversing referrals so that future client-side requests are to traversing referrals so that future client-side requests are
resolved locally without server communication. This is usually resolved locally without server communication. This is usually
rooted in client-side name look up caching. Clients should rooted in client-side name look up caching. Clients should
periodically purge this data for referral points in order to detect periodically purge this data for referral points in order to detect
changes in location information. changes in location information.
A potential problem exists if a client were to allow an open owner to A potential problem exists if a client were to allow an open-owner to
have state on multiple file systems on server, in that it is unclear have state on multiple file systems on server, in that it is unclear
how the sequence numbers associated with open owners are to be dealt how the sequence numbers associated with open-owners are to be dealt
with, in the event of transparent state migration. A client can with, in the event of transparent state migration. A client can
avoid such a situation, if it ensures that any use of an open owner avoid such a situation, if it ensures that any use of an open-owner
is confined to a single file system. is confined to a single file system.
A server MAY decline to migrate state associated with open owners A server MAY decline to migrate state associated with open-owners
that span multiple file systems. In cases in which the server that span multiple file systems. In cases in which the server
chooses not to migrate such state, the server MUST return chooses not to migrate such state, the server MUST return
NFS4ERR_BAD_STATEID when the client uses those stateids on the new NFS4ERR_BAD_STATEID when the client uses those stateids on the new
server. server.
The server MUST return NFS4ERR_STALE_STATEID when the client uses The server MUST return NFS4ERR_STALE_STATEID when the client uses
those stateids on the old server, regardless of whether migration has those stateids on the old server, regardless of whether migration has
occurred or not. occurred or not.
8.7. Effecting File System Referrals 8.7. Effecting File System Referrals
skipping to change at page 91, line 30 skipping to change at page 92, line 39
system) system)
o fsid (value: unique value within referring server) o fsid (value: unique value within referring server)
The attributes for entry "path" will not contain size or time_modify The attributes for entry "path" will not contain size or time_modify
because these attributes are not available within an absent file because these attributes are not available within an absent file
system. system.
8.8. The Attribute fs_locations 8.8. The Attribute fs_locations
The fs_locations attribute is structured in the following way: The fs_locations attribute is defined by both fs_location4
(Section 2.2.6) and fs_locations4 (Section 2.2.7). It is used to
struct fs_location4 { represent the location of a file system by providing a server name
utf8str_cis server<>; and the path to the root of the file system within that server's
pathname4 rootpath; namespace. When a set of servers have corresponding file systems at
}; the same path within their namespaces, an array of server names may
be provided. An entry in the server array is a UTF-8 string and
struct fs_locations4 { represents one of a traditional DNS host name, IPv4 address, IPv6
pathname4 fs_root; address, or a zero-length string. A zero-length string SHOULD be
fs_location4 locations<>; used to indicate the current address being used for the RPC call. It
}; is not a requirement that all servers that share the same rootpath be
listed in one fs_location4 instance. The array of server names is
The fs_location4 data type is used to represent the location of a provided for convenience. Servers that share the same rootpath may
file system by providing a server name and the path to the root of also be listed in separate fs_location4 entries in the fs_locations
the file system within that server's namespace. When a set of attribute.
servers have corresponding file systems at the same path within their
namespaces, an array of server names may be provided. An entry in
the server array is a UTF-8 string and represents one of a
traditional DNS host name, IPv4 address, IPv6 address, or an zero-
length string. A zero-length string SHOULD be used to indicate the
current address being used for the RPC call. It is not a requirement
that all servers that share the same rootpath be listed in one
fs_location4 instance. The array of server names is provided for
convenience. Servers that share the same rootpath may also be listed
in separate fs_location4 entries in the fs_locations attribute.
The fs_locations4 data type and fs_locations attribute contain an The fs_locations4 data type and fs_locations attribute contain an
array of such locations. Since the namespace of each server may be array of such locations. Since the namespace of each server may be
constructed differently, the "fs_root" field is provided. The path constructed differently, the "fs_root" field is provided. The path
represented by fs_root represents the location of the file system in represented by fs_root represents the location of the file system in
the current server's namespace, i.e., that of the server from which the current server's namespace, i.e., that of the server from which
the fs_locations attribute was obtained. The fs_root path is meant the fs_locations attribute was obtained. The fs_root path is meant
to aid the client by clearly referencing the root of the file system to aid the client by clearly referencing the root of the file system
whose locations are being reported, no matter what object within the whose locations are being reported, no matter what object within the
current file system the current filehandle designates. The fs_root current file system the current filehandle designates. The fs_root
skipping to change at page 93, line 24 skipping to change at page 94, line 24
glagoli, and one element in the locations array, with server equal to glagoli, and one element in the locations array, with server equal to
serv2, and rootpath equal to /izhitsa/fita. The client replaces /az/ serv2, and rootpath equal to /izhitsa/fita. The client replaces /az/
buky/vedi/glagoli with /izhitsa/fita, and uses the latter pathname on buky/vedi/glagoli with /izhitsa/fita, and uses the latter pathname on
serv2. serv2.
Thus, the server MUST return an fs_root that is equal to the path the Thus, the server MUST return an fs_root that is equal to the path the
client used to reach the object to which the fs_locations attribute client used to reach the object to which the fs_locations attribute
applies. Otherwise, the client cannot determine the new path to use applies. Otherwise, the client cannot determine the new path to use
on the new server. on the new server.
8.8.1. Inferring Transition Modes
When fs_locations is used, information about the specific locations
should be assumed based on the following rules.
The following rules are general and apply irrespective of the
context.
o All listed file system instances should be considered as being of
the same handle class if and only if the current fh_expire_type
attribute does not include the FH4_VOL_MIGRATION bit. Note that
in the case of referral, filehandle issues do not apply since
there can be no filehandles known within the current file system
nor is there any access to the fh_expire_type attribute on the
referring (absent) file system.
o All listed file system instances should be considered as being of
the same fileid class if and only if the fh_expire_type attribute
indicates persistent filehandles and does not include the
FH4_VOL_MIGRATION bit. Note that in the case of referral, fileid
issues do not apply since there can be no fileids known within the
referring (absent) file system nor is there any access to the
fh_expire_type attribute.
o All file system instances should be considered as being of
different change classes.
o All file system instances servers should be considered as being of
different readdir classes.
For other class assignments, handling of file system transitions
depends on the reasons for the transition:
o When the transition is due to migration, that is, the client was
directed to a new file system after receiving an NFS4ERR_MOVED
error, the target should be treated as being of the same write-
verifier class as the source.
o When the transition is due to failover to another replica, that
is, the client selected another replica without receiving and
NFS4ERR_MOVED error, the target should be treated as being of a
different write-verifier class from the source.
The specific choices reflect typical implementation patterns for
failover and controlled migration, respectively.
See Section 17 for a discussion on the recommendations for the
security flavor to be used by any GETATTR operation that requests the
"fs_locations" attribute.
9. File Locking and Share Reservations 9. File Locking and Share Reservations
Integrating locking into the NFS protocol necessarily causes it to be Integrating locking into the NFS protocol necessarily causes it to be
stateful. With the inclusion of share reservations the protocol stateful. With the inclusion of share reservations the protocol
becomes substantially more dependent on state than the traditional becomes substantially more dependent on state than the traditional
combination of NFS and NLM (Network Lock Manager) [xnfs]. There are combination of NFS and NLM (Network Lock Manager) [xnfs]. There are
three components to making this state manageable: three components to making this state manageable:
o clear division between client and server o clear division between client and server
skipping to change at page 98, line 16 skipping to change at page 98, line 16
* A true random number. However since this number ought to be * A true random number. However since this number ought to be
the same between client incarnations, this shares the same the same between client incarnations, this shares the same
problem as that of the using the timestamp of the software problem as that of the using the timestamp of the software
installation. installation.
As a security measure, the server MUST NOT cancel a client's leased As a security measure, the server MUST NOT cancel a client's leased
state if the principal that established the state for a given id state if the principal that established the state for a given id
string is not the same as the principal issuing the SETCLIENTID. string is not the same as the principal issuing the SETCLIENTID.
Note that SETCLIENTID and SETCLIENTID_CONFIRM has a secondary purpose Note that SETCLIENTID (Section 15.35) and SETCLIENTID_CONFIRM
of establishing the information the server needs to make callbacks to (Section 15.36) have a secondary purpose of establishing the
the client for purpose of supporting delegations. It is permitted to information the server needs to make callbacks to the client for the
change this information via SETCLIENTID and SETCLIENTID_CONFIRM purpose of supporting delegations. It is permitted to change this
within the same incarnation of the client without removing the information via SETCLIENTID and SETCLIENTID_CONFIRM within the same
client's leased state. incarnation of the client without removing the client's leased state.
Once a SETCLIENTID and SETCLIENTID_CONFIRM sequence has successfully Once a SETCLIENTID and SETCLIENTID_CONFIRM sequence has successfully
completed, the client uses the shorthand client identifier, of type completed, the client uses the shorthand client identifier, of type
clientid4, instead of the longer and less compact nfs_client_id4 clientid4, instead of the longer and less compact nfs_client_id4
structure. This shorthand client identifier (a client ID) is structure. This shorthand client identifier (a client ID) is
assigned by the server and should be chosen so that it will not assigned by the server and should be chosen so that it will not
conflict with a client ID previously assigned by the server. This conflict with a client ID previously assigned by the server. This
applies across server restarts or reboots. When a client ID is applies across server restarts or reboots. When a client ID is
presented to a server and that client ID is not recognized, as would presented to a server and that client ID is not recognized, as would
happen after a server reboot, the server will reject the request with happen after a server reboot, the server will reject the request with
skipping to change at page 98, line 43 skipping to change at page 98, line 43
obtain a new client ID by use of the SETCLIENTID operation and then obtain a new client ID by use of the SETCLIENTID operation and then
proceed to any other necessary recovery for the server reboot case proceed to any other necessary recovery for the server reboot case
(See Section 9.6.2). (See Section 9.6.2).
The client must also employ the SETCLIENTID operation when it The client must also employ the SETCLIENTID operation when it
receives a NFS4ERR_STALE_STATEID error using a stateid derived from receives a NFS4ERR_STALE_STATEID error using a stateid derived from
its current client ID, since this also indicates a server reboot its current client ID, since this also indicates a server reboot
which has invalidated the existing client ID (see Section 9.6.2 for which has invalidated the existing client ID (see Section 9.6.2 for
details). details).
See the detailed descriptions of SETCLIENTID and SETCLIENTID_CONFIRM See the detailed descriptions of SETCLIENTID (Section 15.35.4) and
for a complete specification of the operations. SETCLIENTID_CONFIRM (Section 15.36.4) for a complete specification of
the operations.
9.1.2. Server Release of Client ID 9.1.2. Server Release of Client ID
If the server determines that the client holds no associated state If the server determines that the client holds no associated state
for its client ID, the server may choose to release the client ID. for its client ID, the server may choose to release the client ID.
The server may make this choice for an inactive client so that The server may make this choice for an inactive client so that
resources are not consumed by those intermittently active clients. resources are not consumed by those intermittently active clients.
If the client contacts the server after this release, the server must If the client contacts the server after this release, the server must
ensure the client receives the appropriate error so that it will use ensure the client receives the appropriate error so that it will use
the SETCLIENTID/SETCLIENTID_CONFIRM sequence to establish a new the SETCLIENTID/SETCLIENTID_CONFIRM sequence to establish a new
identity. It should be clear that the server must be very hesitant identity. It should be clear that the server must be very hesitant
to release a client ID since the resulting work on the client to to release a client ID since the resulting work on the client to
recover from such an event will be the same burden as if the server recover from such an event will be the same burden as if the server
had failed and restarted. Typically a server would not release a had failed and restarted. Typically a server would not release a
client ID unless there had been no activity from that client for many client ID unless there had been no activity from that client for many
minutes. minutes.
skipping to change at page 99, line 33 skipping to change at page 99, line 33
that changes security flavors, and under the new flavor, there is no that changes security flavors, and under the new flavor, there is no
mapping to the previous owner) will in rare cases result in mapping to the previous owner) will in rare cases result in
NFS4ERR_CLID_INUSE. NFS4ERR_CLID_INUSE.
In that event, when the server gets a SETCLIENTID for a client ID In that event, when the server gets a SETCLIENTID for a client ID
that currently has no state, or it has state, but the lease has that currently has no state, or it has state, but the lease has
expired, rather than returning NFS4ERR_CLID_INUSE, the server MUST expired, rather than returning NFS4ERR_CLID_INUSE, the server MUST
allow the SETCLIENTID, and confirm the new client ID if followed by allow the SETCLIENTID, and confirm the new client ID if followed by
the appropriate SETCLIENTID_CONFIRM. the appropriate SETCLIENTID_CONFIRM.
9.1.3. Stateid Definition 9.1.3. Use of Seqids
In several contexts, 32-bit sequence values, called "seqids" are used
as part of managing locking state. Such values are used:
o To provide an ordering of locking-related operations associated
with a particular lock-owner or open-owner. See Section 9.1.7 for
a detailed explanation.
o To define an ordered set of instances of a set of locks sharing a
particular set of ownership characteristics. See Section 9.1.4.2
for a detailed explanation.
Successive seqid values for the same object are normally arrived at
by incrementing the current value by one. This pattern continues
until the seqid is incremented past NFS4_UINT32_MAX, in which case
one (rather than zero) is to be the next seqid value.
When two seqid values are to be compared to determine which of the
two is later, the possibility of wraparound needs to be considered.
In many cases, the values are such that simple numeric comparisons
can be used. For example, if the seqid values to be compared are
both less than one million, the higher value can be considered the
later. On the other hand, if one of the values is at or near
NFS_UINT32_MAX and the other is less than one million, then
implementations can reasonably decide that the lower value has had
one more wraparound and is thus, while numerically lower, actually
later.
Implementations can compare seqids in the presence of potential
wraparound by adopting the reasonable assumption that the chain of
increments from one to the other is shorter than 2**31. So, if the
difference between the two seqids is less than 2**31, then the lower
seqid is to be treated as earlier. If, however, the difference
between the two seqids is greater than or equal to 2**31, then it can
be assumed that the lower seqid has encountered one more wraparound
and can be treated as later.
9.1.4. Stateid Definition
When the server grants a lock of any type (including opens, byte- When the server grants a lock of any type (including opens, byte-
range locks, and delegations), it responds with a unique stateid that range locks, and delegations), it responds with a unique stateid that
represents a set of locks (often a single lock) for the same file, of represents a set of locks (often a single lock) for the same file, of
the same type, and sharing the same ownership characteristics. Thus, the same type, and sharing the same ownership characteristics. Thus,
opens of the same file by different open-owners each have an opens of the same file by different open-owners each have an
identifying stateid. Similarly, each set of byte-range locks on a identifying stateid. Similarly, each set of byte-range locks on a
file owned by a specific lock-owner has its own identifying stateid. file owned by a specific lock-owner has its own identifying stateid.
Delegations also have associated stateids by which they may be Delegations also have associated stateids by which they may be
referenced. The stateid is used as a shorthand reference to a lock referenced. The stateid is used as a shorthand reference to a lock
skipping to change at page 100, line 11 skipping to change at page 101, line 5
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.
Each stateid must be unique to the server. Many operations take a Each stateid must be unique to the server. Many operations take a
stateid as an argument but not a clientid, so the server must be able stateid as an argument but not a clientid, so the server must be able
to infer the client from the stateid. to infer the client from the stateid.
9.1.3.1. Stateid Types 9.1.4.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.4.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 a guarantee, it is understood there are situations such as a
restart, or lock revocation, that allow the guarantee to be voided. client 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.
Each stateid in this case represents the OPEN state for a given Each stateid in this case represents the OPEN state for a given
client ID/open-owner/filehandle triple. Such stateids are subject client ID/open-owner/filehandle triple. Such stateids are subject
to change (with consequent incrementing of the stateid's seqid) in to change (with consequent incrementing of the stateid's seqid) in
response to OPENs that result in upgrade and OPEN_DOWNGRADE response to OPENs that result in upgrade and OPEN_DOWNGRADE
operations. operations.
o Stateids may represent sets of byte-range locks. o Stateids may represent sets of byte-range locks.
skipping to change at page 100, line 42 skipping to change at page 101, line 37
LOCK and LOCKU operations affect that set of locks. LOCK and LOCKU operations affect that set of locks.
o Stateids may represent file delegations, which are recallable o Stateids may represent file delegations, which are recallable
guarantees by the server to the client that other clients will not guarantees by the server to the client that other clients will not
reference, or will not modify, a particular file until the reference, or will not modify, a particular file until the
delegation is returned. delegation is returned.
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.4.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.4.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, or delegations), for same type (for example, byte-range locks, opens, or delegations), for
a specific file or directory, and sharing the same ownership a specific file or directory, and sharing the same ownership
characteristics. The seqid designates a specific instance of such a characteristics. The seqid designates a specific instance of such a
set of locks, and is incremented to indicate changes in such a set of set of locks, and is incremented to indicate changes in such a set of
locks, either by the addition or deletion of locks from the set, a locks, either by the addition or deletion of locks from the set, a
change in the byte-range they apply to, or an upgrade or downgrade in change in the byte-range they apply to, or an upgrade or 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 SHOULD return a When such a set of locks is first created, the server returns 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 advance 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 the operation is one that might
of locks actually designated. In this case, the server will return a make some change in the set of locks actually designated. In this
stateid with an "other" field the same as previously used for that case, the server will return a stateid with an "other" field the same
state-owner/file/type combination, with an incremented "seqid" field. as previously used for that state-owner/file/type combination, with
This pattern continues until the seqid is incremented past an incremented "seqid" field.
NFS4_UINT32_MAX, and one (not zero) SHOULD be the next seqid value.
The purpose of the incrementing of the seqid is to allow the server
to communicate to the client the order in which operations that
modified locking state associated with a stateid have been processed.
In making comparisons between seqids, both by the client in Seqids will be compared, by both the client and the server. The
determining the order of operations and by the server in determining client uses such comparisons to determine the order of operations
whether the NFS4ERR_OLD_STATEID is to be returned, the possibility of while the server uses them to determine whether the
the seqid being swapped around past the NFS4_UINT32_MAX value needs NFS4ERR_OLD_STATEID error is to be returned. In all cases, the
to be taken into account. possibility of seqid wraparound needs to be taken into account, as
discussed in Section 9.1.3
9.1.3.3. Special Stateids 9.1.4.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
are reserved. They may not be assigned by the server but have are reserved. They MUST NOT be assigned by the server but have
special meanings defined by the protocol. The particular meaning special meanings defined by the protocol. The particular meaning
depends on whether the "other" field is all zeros or all ones and the depends on whether the "other" field is all zeros or all ones and the
specific value of the "seqid" field. specific value of the "seqid" field.
The following combinations of "other" and "seqid" are defined in The following combinations of "other" and "seqid" are defined in
NFSv4: NFSv4:
o When "other" and "seqid" are both zero, the stateid is treated as Anonymous Stateid: When "other" and "seqid" are both zero, the
a special anonymous stateid, which can be used in READ, WRITE, and stateid is treated as a special anonymous stateid, which can be
SETATTR requests to indicate the absence of any open state used in READ, WRITE, and SETATTR requests to indicate the absence
associated with the request. When an anonymous stateid value is of any open state associated with the request. When an anonymous
used, and an existing open denies the form of access requested, stateid value is used, and an existing open denies the form of
then access will be denied to the request. access requested, then access will be denied to the request.
o When "other" and "seqid" are both all ones, the stateid is a READ Bypass Stateid: When "other" and "seqid" are both all ones, the
special READ bypass stateid. When this value is used in WRITE or stateid is a special READ bypass stateid. When this value is used
SETATTR, it is treated like the anonymous value. When used in in WRITE or SETATTR, it is treated like the anonymous value. When
READ, the server MAY grant access, even if access would normally used in READ, the server MAY grant access, even if access would
be denied to READ requests. normally be denied to READ requests.
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. client IDs and filehandles.
9.1.3.4. Stateid Lifetime and Validation 9.1.4.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
the open file with which they are associated remains open. the open file with which they are associated remains open.
skipping to change at page 103, line 19 skipping to change at page 104, line 11
o The last "seqid" value returned corresponding to the current o The last "seqid" value returned corresponding to the current
"other" value. "other" value.
o An indication of the current status of the locks associated with o An indication of the current status of the locks associated with
this stateid. In particular, whether these have been revoked and this stateid. In particular, whether these have been revoked and
if so, for what reason. if so, for what reason.
With this information, an incoming stateid can be validated and the With this information, an incoming stateid can be validated and the
appropriate error returned when necessary. Special and non-special appropriate error returned when necessary. Special and non-special
stateids are handled separately. (See Section 9.1.3.3 for a stateids are handled separately. (See Section 9.1.4.3 for a
discussion of special stateids.) discussion of special stateids.)
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.
skipping to change at page 103, line 43 skipping to change at page 104, line 35
stateid is used when an open stateid is required in a LOCK stateid is used when an open stateid is required in a LOCK
operation), the 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. Note that the terms "earlier" and "later"
used in connection with seqid comparison are to be understood as
explained in Section 9.1.3.
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.
skipping to change at page 104, line 18 skipping to change at page 105, line 14
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 later than the current
current sequence value corresponding the current "other" field, sequence value corresponding to the current "other" field, return
return NFS4ERR_BAD_STATEID. NFS4ERR_BAD_STATEID.
o If the "seqid" field is less than the current sequence value o If the "seqid" field is earlier than the current sequence value
corresponding the current "other" field, return corresponding to 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.4.5. Stateid Use for I/O Operations
Clients performing Input/Output (I/O) operations need to select an Clients performing Input/Output (I/O) operations need to select an
appropriate stateid based on the locks (including opens and appropriate stateid based on the locks (including opens and
delegations) held by the client and the various types of state-owners delegations) held by the client and the various types of state-owners
sending the I/O requests. SETATTR operations that change the file sending the I/O requests. SETATTR operations that change the file
size are treated like I/O operations in this regard. size are treated like I/O operations in this regard.
The following rules, applied in order of decreasing priority, govern The following rules, applied in order of decreasing priority, govern
the selection of the appropriate stateid. In following these rules, the selection of the appropriate stateid. In following these rules,
the client will only consider locks of which it has actually received the client will only consider locks of which it has actually received
skipping to change at page 105, line 6 skipping to change at page 105, line 51
o If the client holds a delegation for the file in question, the o If the client holds a delegation for the file in question, the
delegation stateid SHOULD be used. delegation stateid SHOULD be used.
o Otherwise, if the entity corresponding to the lock-owner (e.g., a o Otherwise, if the entity corresponding to the lock-owner (e.g., a
process) sending the I/O has a byte-range lock stateid for the process) sending the I/O has a byte-range lock stateid for the
associated open file, then the byte-range lock stateid for that associated open file, then the byte-range lock stateid for that
lock-owner and open file SHOULD be used. lock-owner and open file SHOULD be used.
o If there is no byte-range lock stateid, then the OPEN stateid for o If there is no byte-range lock stateid, then the OPEN stateid for
the current open-owner, and that OPEN stateid for the open file in the current open-owner, i.e., the OPEN stateid for the open file
question SHOULD be used. in question, SHOULD be used.
o Finally, if none of the above apply, then a special stateid SHOULD o Finally, if none of the above apply, then a special stateid SHOULD
be used. be used.
Ignoring these rules may result in situations in which the server Ignoring these rules may result in situations in which the server
does not have information necessary to properly process the request. does not have information necessary to properly process the request.
For example, when mandatory byte-range locks are in effect, if the For example, when mandatory byte-range locks are in effect, if the
stateid does not indicate the proper lock-owner, via a lock stateid, stateid does not indicate the proper lock-owner, via a lock stateid,
a request might be avoidably rejected. a request might be avoidably rejected.
The server however should not try to enforce these ordering rules and The server however should not try to enforce these ordering rules and
should use whatever information is available to properly process I/O should use whatever information is available to properly process I/O
requests. In particular, when a client has a delegation for a given requests. In particular, when a client has a delegation for a given
file, it SHOULD take note of this fact in processing a request, even file, it SHOULD take note of this fact in processing a request, even
if it is sent with a special stateid. if it is sent with a special stateid.
9.1.3.6. Stateid Use for SETATTR Operations 9.1.4.6. Stateid Use for SETATTR Operations
In the case of SETATTR operations, a stateid is present. In cases In the case of SETATTR operations, a stateid is present. In cases
other than those that set the file size, the client may send either a other than those that set the file size, the client may send either a
special stateid or, when a delegation is held for the file in special stateid or, when a delegation is held for the file in
question, a delegation stateid. While the server SHOULD validate the question, a delegation stateid. While the server SHOULD validate the
stateid and may use the stateid to optimize the determination as to stateid and may use the stateid to optimize the determination as to
whether a delegation is held, it SHOULD note the presence of a whether a delegation is held, it SHOULD note the presence of a
delegation even when a special stateid is sent, and MUST accept a delegation even when a special stateid is sent, and MUST accept a
valid delegation stateid when sent. valid delegation stateid when sent.
9.1.4. lock-owner 9.1.5. lock-owner
When requesting a lock, the client must present to the server the When requesting a lock, the client must present to the server the
client ID and an identifier for the owner of the requested lock. client ID and an identifier for the owner of the requested lock.
These two fields are referred to as the lock-owner and the definition These two fields are referred to as the lock-owner and the definition
of those fields are: of those fields are:
o A client ID returned by the server as part of the client's use of o A client ID returned by the server as part of the client's use of
the SETCLIENTID operation. the SETCLIENTID operation.
o A variable length opaque array used to uniquely define the owner o A variable length opaque array used to uniquely define the owner
of a lock managed by the client. of a lock managed by the client.
This may be a thread id, process id, or other unique value. This may be a thread id, process id, or other unique value.
When the server grants the lock, it responds with a unique stateid. When the server grants the lock, it responds with a unique stateid.
The stateid is used as a shorthand reference to the lock-owner, since The stateid is used as a shorthand reference to the lock-owner, since
the server will be maintaining the correspondence between them. the server will be maintaining the correspondence between them.
9.1.5. Use of the Stateid and Locking 9.1.6. Use of the Stateid and Locking
All READ, WRITE and SETATTR operations contain a stateid. For the All READ, WRITE and SETATTR operations contain a stateid. For the
purposes of this section, SETATTR operations which change the size purposes of this section, SETATTR operations which change the size
attribute of a file are treated as if they are writing the area attribute of a file are treated as if they are writing the area
between the old and new size (i.e., the range truncated or added to between the old and new size (i.e., the range truncated or added to
the file by means of the SETATTR), even where SETATTR is not the file by means of the SETATTR), even where SETATTR is not
explicitly mentioned in the text. The stateid passed to one of these explicitly mentioned in the text. The stateid passed to one of these
operations must be one that represents an OPEN (e.g., via the open- operations must be one that represents an OPEN (e.g., via the open-
owner), a set of byte-range locks, or a delegation, or it may be a owner), a set of byte-range locks, or a delegation, or it may be a
special stateid representing anonymous access or the special bypass special stateid representing anonymous access or the READ bypass
stateid. stateid.
If the state-owner performs a READ or WRITE in a situation in which If the state-owner performs a READ or WRITE in a situation in which
it has established a lock or share reservation on the server (any it has established a lock or share reservation on the server (any
OPEN constitutes a share reservation) the stateid (previously OPEN constitutes a share reservation) the stateid (previously
returned by the server) must be used to indicate what locks, returned by the server) must be used to indicate what locks,
including both byte-range locks and share reservations, are held by including both byte-range locks and share reservations, are held by
the state-owner. If no state is established by the client, either the state-owner. If no state is established by the client, either
byte-range lock or share reservation, a stateid of all bits 0 is byte-range lock or share reservation, the anonymous stateid is used.
used. Regardless whether a stateid of all bits 0, or a stateid Regardless whether an anonymous stateid or a stateid returned by the
returned by the server is used, if there is a conflicting share server is used, if there is a conflicting share reservation or
reservation or mandatory byte-range lock held on the file, the server mandatory byte-range lock held on the file, the server MUST refuse to
MUST refuse to service the READ or WRITE operation. service the READ or WRITE operation.
Share reservations are established by OPEN operations and by their Share reservations are established by OPEN operations and by their
nature are mandatory in that when the OPEN denies READ or WRITE nature are mandatory in that when the OPEN denies READ or WRITE
operations, that denial results in such operations being rejected operations, that denial results in such operations being rejected
with error NFS4ERR_LOCKED. Byte-range locks may be implemented by with error NFS4ERR_LOCKED. Byte-range locks may be implemented by
the server as either mandatory or advisory, or the choice of the server as either mandatory or advisory, or the choice of
mandatory or advisory behavior may be determined by the server on the mandatory or advisory behavior may be determined by the server on the
basis of the file being accessed (for example, some UNIX-based basis of the file being accessed (for example, some UNIX-based
servers support a "mandatory lock bit" on the mode attribute such servers support a "mandatory lock bit" on the mode attribute such
that if set, byte-range locks are required on the file before I/O is that if set, byte-range locks are required on the file before I/O is
skipping to change at page 108, line 5 skipping to change at page 109, line 5
mode, or it may choose to allow READ on opens for WRITE only, to mode, or it may choose to allow READ on opens for WRITE only, to
accommodate clients whose write implementation may unavoidably do accommodate clients whose write implementation may unavoidably do
reads (e.g., due to buffer cache constraints). However, even if reads (e.g., due to buffer cache constraints). However, even if
READs are allowed in these circumstances, the server MUST still check READs are allowed in these circumstances, the server MUST still check
for locks that conflict with the READ (e.g., another open specifying for locks that conflict with the READ (e.g., another open specifying
denial of READs). Note that a server which does enforce the access denial of READs). Note that a server which does enforce the access
mode check on READs need not explicitly check for conflicting share mode check on READs need not explicitly check for conflicting share
reservations since the existence of OPEN for read access guarantees reservations since the existence of OPEN for read access guarantees
that no conflicting share reservation can exist. that no conflicting share reservation can exist.
A stateid of all bits 1 (one) MAY allow READ operations to bypass A READ bypass stateid MAY allow READ operations to bypass locking
locking checks at the server. However, WRITE operations with a checks at the server. However, WRITE operations with a READ bypass
stateid with bits all 1 (one) MUST NOT bypass locking checks and are stateid MUST NOT bypass locking checks and are treated exactly the
treated exactly the same as if a stateid of all bits 0 were used. same as if an anonymous stateid were used.
A lock may not be granted while a READ or WRITE operation using one A lock may not be granted while a READ or WRITE operation using one
of the special stateids is being performed and the range of the lock of the special stateids is being performed and the range of the lock
request conflicts with the range of the READ or WRITE operation. For request conflicts with the range of the READ or WRITE operation. For
the purposes of this paragraph, a conflict occurs when a shared lock the purposes of this paragraph, a conflict occurs when a shared lock
is requested and a WRITE operation is being performed, or an is requested and a WRITE operation is being performed, or an
exclusive lock is requested and either a READ or a WRITE operation is exclusive lock is requested and either a READ or a WRITE operation is
being performed. A SETATTR that sets size is treated similarly to a being performed. A SETATTR that sets size is treated similarly to a
WRITE as discussed above. WRITE as discussed above.
9.1.6. Sequencing of Lock Requests 9.1.7. Sequencing of Lock Requests
Locking is different than most NFS operations as it requires "at- Locking is different than most NFS operations as it requires "at-
most-one" semantics that are not provided by ONC RPC. ONC RPC over a most-one" semantics that are not provided by ONC RPC. ONC RPC over a
reliable transport is not sufficient because a sequence of locking reliable transport is not sufficient because a sequence of locking
requests may span multiple TCP connections. In the face of requests may span multiple TCP connections. In the face of
retransmission or reordering, lock or unlock requests must have a retransmission or reordering, lock or unlock requests must have a
well defined and consistent behavior. To accomplish this, each lock well defined and consistent behavior. To accomplish this, each lock
request contains a sequence number that is a consecutively increasing request contains a sequence number that is a consecutively increasing
integer. Different state-owners have different sequences. The integer. Different state-owners have different sequences. The
server maintains the last sequence number (L) received and the server maintains the last sequence number (L) received and the
response that was returned. The server SHOULD assign a seqid value response that was returned. The server SHOULD assign a seqid value
of one for the first request issued for any given state-owner. of one for the first request issued for any given state-owner.
Subsequent values are arrived at by incrementing the seqid value,
subject to wraparound as described in Section 9.1.3.
Note that for requests that contain a sequence number, for each Note that for requests that contain a sequence number, for each
state-owner, there should be no more than one outstanding request. state-owner, there should be no more than one outstanding request.
If a request (r) with a previous sequence number (r < L) is received, When a request is received, its sequence number (r) is compared to
it is rejected with the return of error NFS4ERR_BAD_SEQID. Given a that of the last one received (L). Only if it has the correct next
properly-functioning client, the response to (r) must have been sequence, normally L + 1, is the request processed beyond the point
received before the last request (L) was sent. If a duplicate of of seqid checking. Given a properly-functioning client, the response
last request (r == L) is received, the stored response is returned. to (r) must have been received before the last request (L) was sent.
If a request beyond the next sequence (r == L + 2) is received, it is If a duplicate of last request (r == L) is received, the stored
rejected with the return of error NFS4ERR_BAD_SEQID. Sequence response is returned. If the sequence value received is any other
history is reinitialized whenever the SETCLIENTID/SETCLIENTID_CONFIRM value, it is rejected with the return of error NFS4ERR_BAD_SEQID.
sequence changes the client verifier. Sequence history is reinitialized whenever the SETCLIENTID/
SETCLIENTID_CONFIRM sequence changes the client verifier.
Since the sequence number is represented with an unsigned 32-bit
integer, the arithmetic involved with the sequence number is mod
2^32. Note that when the seqid wraps, it SHOULD bypass zero and use
one as the next seqid value. For an example of modulo arithmetic
involving sequence numbers see [RFC0793].
It is critical the server maintain the last response sent to the It is critical the server maintain the last response sent to the
client to provide a more reliable cache of duplicate non-idempotent client to provide a more reliable cache of duplicate non-idempotent
requests than that of the traditional cache described in [Chet]. The requests than that of the traditional cache described in [Chet]. The
traditional duplicate request cache uses a least recently used traditional duplicate request cache uses a least recently used
algorithm for removing unneeded requests. However, the last lock algorithm for removing unneeded requests. However, the last lock
request and response on a given state-owner must be cached as long as request and response on a given state-owner must be cached as long as
the lock state exists on the server. the lock state exists on the server.
The client MUST monotonically increment the sequence number for the The client MUST advance the sequence number for the CLOSE, LOCK,
CLOSE, LOCK, LOCKU, OPEN, OPEN_CONFIRM, and OPEN_DOWNGRADE LOCKU, OPEN, OPEN_CONFIRM, and OPEN_DOWNGRADE operations. This is
operations. This is true even in the event that the previous true even in the event that the previous operation that used the
operation that used the sequence number received an error. The only sequence number received an error. The only exception to this rule
exception to this rule is if the previous operation received one of is if the previous operation received one of the following errors:
the following errors: NFS4ERR_STALE_CLIENTID, NFS4ERR_STALE_STATEID, NFS4ERR_STALE_CLIENTID, NFS4ERR_STALE_STATEID, NFS4ERR_BAD_STATEID,
NFS4ERR_BAD_STATEID, NFS4ERR_BAD_SEQID, NFS4ERR_BADXDR, NFS4ERR_BAD_SEQID, NFS4ERR_BADXDR, NFS4ERR_RESOURCE,
NFS4ERR_RESOURCE, NFS4ERR_NOFILEHANDLE, or NFS4ERR_MOVED. NFS4ERR_NOFILEHANDLE, or NFS4ERR_MOVED.
9.1.7. Recovery from Replayed Requests 9.1.8. Recovery from Replayed Requests
As described above, the sequence number is per state-owner. As long As described above, the sequence number is per state-owner. As long
as the server maintains the last sequence number received and follows as the server maintains the last sequence number received and follows
the methods described above, there are no risks of a Byzantine router the methods described above, there are no risks of a Byzantine router
re-sending old requests. The server need only maintain the (state- re-sending old requests. The server need only maintain the (state-
owner, sequence number) state as long as there are open files or owner, sequence number) state as long as there are open files or
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.9. 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 retransmission 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.
skipping to change at page 110, line 28 skipping to change at page 111, line 23
but the operations are not the same, NFS4ERR_BAD_SEQID is but the operations are not the same, NFS4ERR_BAD_SEQID is
returned. 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_CONFIRM 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).
9.1.9. Releasing state-owner State 9.1.10. 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
have if the state-owner state was not released. have if the state-owner state was not released.
skipping to change at page 110, line 50 skipping to change at page 111, line 45
If the server were able to be sure that a given state-owner would If the server were able to be sure that a given state-owner would
never again be used by a client, such an issue could not arise. Even never again be used by a client, such an issue could not arise. Even
when the state-owner state is released and the client subsequently when the state-owner state is released and the client subsequently
uses that state-owner, retransmitted requests will be detected as uses that state-owner, retransmitted requests will be detected as
invalid and the request not executed, although the client may have a invalid and the request not executed, although the client may have a
recovery path that is more complicated than simply getting the recovery path that is more complicated than simply getting the
original response back transparently. original response back transparently.
In any event, the server is able to safely release state-owner state In any event, the server is able to safely release state-owner state
(in the sense that retransmitted requests will not be erroneously (in the sense that retransmitted requests will not be erroneously
acted upon) when the state-owner no currently being utilized by the acted upon) when the state-owner is not currently being utilized by
client (i.e., there are no open files associated with an open-owner the client (i.e., there are no open files associated with an open-
and no lock stateids associated with a lock-owner). The server may owner and no lock stateids associated with a lock-owner). The server
choose to hold the state-owner state in order to simplify the may choose to hold the state-owner state in order to simplify the
recovery path, in the case in which retransmissions of currently recovery path, in the case in which retransmissions of currently
active requests are received. However, the period it chooses to hold active requests are received. However, the period for which it
this state is implementation specific. chooses to hold this state is implementation specific.
In the case that a LOCK, LOCKU, OPEN_DOWNGRADE, or CLOSE is In the case that a LOCK, LOCKU, OPEN_DOWNGRADE, or CLOSE is
retransmitted after the server has previously released the state- retransmitted after the server has previously released the state-
owner state, the server will find that the state-owner has no files owner state, the server will find that the state-owner has no files
open and an error will be returned to the client. If the state-owner open and an error will be returned to the client. If the state-owner
does have a file open, the stateid will not match and again an error does have a file open, the stateid will not match and again an error
is returned to the client. is returned to the client.
9.1.10. Use of Open Confirmation 9.1.11. Use of Open Confirmation
In the case that an OPEN is retransmitted and the open-owner is being In the case that an OPEN is retransmitted and the open-owner is being
used for the first time or the open-owner state has been previously used for the first time or the open-owner state has been previously
released by the server, the use of the OPEN_CONFIRM operation will released by the server, the use of the OPEN_CONFIRM operation will
prevent incorrect behavior. When the server observes the use of the prevent incorrect behavior. When the server observes the use of the
open-owner for the first time, it will direct the client to perform open-owner for the first time, it will direct the client to perform
the OPEN_CONFIRM for the corresponding OPEN. This sequence the OPEN_CONFIRM for the corresponding OPEN. This sequence
establishes the use of a open-owner and associated sequence number. establishes the use of a open-owner and associated sequence number.
Since the OPEN_CONFIRM sequence connects a new open-owner on the Since the OPEN_CONFIRM sequence connects a new open-owner on the
server with an existing open-owner on a client, the sequence number server with an existing open-owner on a client, the sequence number
may have any value. The OPEN_CONFIRM step assures the server that may have any valid (i.e., non-zero) value. The OPEN_CONFIRM step
the value received is the correct one. (see Section 15.20 for assures the server that the value received is the correct one. (see
further details.) Section 15.20 for further details.)
There are a number of situations in which the requirement to confirm There are a number of situations in which the requirement to confirm
an OPEN would pose difficulties for the client and server, in that an OPEN would pose difficulties for the client and server, in that
they would be prevented from acting in a timely fashion on they would be prevented from acting in a timely fashion on
information received, because that information would be provisional, information received, because that information would be provisional,
subject to deletion upon non-confirmation. Fortunately, these are subject to deletion upon non-confirmation. Fortunately, these are
situations in which the server can avoid the need for confirmation situations in which the server can avoid the need for confirmation
when responding to open requests. The two constraints are: when responding to open requests. The two constraints are:
o The server must not bestow a delegation for any open which would o The server must not bestow a delegation for any open which would
skipping to change at page 112, line 22 skipping to change at page 113, line 16
Requiring open confirmation on reclaim-type opens is avoidable Requiring open confirmation on reclaim-type opens is avoidable
because of the nature of the environments in which such opens are because of the nature of the environments in which such opens are
done. For CLAIM_PREVIOUS opens, this is immediately after server done. For CLAIM_PREVIOUS opens, this is immediately after server
reboot, so there should be no time for open-owners to be created, reboot, so there should be no time for open-owners to be created,
found to be unused, and recycled. For CLAIM_DELEGATE_PREV opens, we found to be unused, and recycled. For CLAIM_DELEGATE_PREV opens, we
are dealing with either a client reboot situation or a network are dealing with either a client reboot situation or a network
partition resulting in deletion of lease state (and returning partition resulting in deletion of lease state (and returning
NFS4ERR_EXPIRED). A server which supports delegations can be sure NFS4ERR_EXPIRED). A server which supports delegations can be sure
that no open-owners for that client have been recycled since client that no open-owners for that client have been recycled since client
initialization or deletion of lease state and thus can ensure that initialization or deletion of lease state and thus can be confident
confirmation will not be required. that confirmation will not be required.
9.2. Lock Ranges 9.2. Lock Ranges
The protocol allows a lock owner to request a lock with a byte range The protocol allows a lock-owner to request a lock with a byte range
and then either upgrade or unlock a sub-range of the initial lock. and then either upgrade or unlock a sub-range of the initial lock.
It is expected that this will be an uncommon type of request. In any It is expected that this will be an uncommon type of request. In any
case, servers or server file systems may not be able to support sub- case, servers or server file systems may not be able to support sub-
range lock semantics. In the event that a server receives a locking range lock semantics. In the event that a server receives a locking
request that represents a sub-range of current locking state for the request that represents a sub-range of current locking state for the
lock owner, the server is allowed to return the error lock-owner, the server is allowed to return the error
NFS4ERR_LOCK_RANGE to signify that it does not support sub-range lock NFS4ERR_LOCK_RANGE to signify that it does not support sub-range lock
operations. Therefore, the client should be prepared to receive this operations. Therefore, the client should be prepared to receive this
error and, if appropriate, report the error to the requesting error and, if appropriate, report the error to the requesting
application. application.
The client is discouraged from combining multiple independent locking The client is discouraged from combining multiple independent locking
ranges that happen to be adjacent into a single request since the ranges that happen to be adjacent into a single request since the
server may not support sub-range requests and for reasons related to server may not support sub-range requests and for reasons related to
the recovery of file locking state in the event of server failure. the recovery of file locking state in the event of server failure.
As discussed in the Section 9.6.2 below, the server may employ As discussed in the Section 9.6.2 below, the server may employ
skipping to change at page 114, line 28 skipping to change at page 115, line 24
renewals may not be denied if the lease interval has not expired. renewals may not be denied if the lease interval has not expired.
The client can implicitly provide a positive indication that it is The client can implicitly provide a positive indication that it is
still active and that the associated state held at the server, for still active and that the associated state held at the server, for
the client, is still valid. Any operation made with a valid clientid the client, is still valid. Any operation made with a valid clientid
(DELEGPURGE, LOCK, LOCKT, OPEN, RELEASE_LOCKOWNER, or RENEW) or a (DELEGPURGE, LOCK, LOCKT, OPEN, RELEASE_LOCKOWNER, or RENEW) or a
valid stateid (CLOSE, DELEGRETURN, LOCK, LOCKU, OPEN, OPEN_CONFIRM, valid stateid (CLOSE, DELEGRETURN, LOCK, LOCKU, OPEN, OPEN_CONFIRM,
OPEN_DOWNGRADE, READ, SETATTR, or WRITE) informs the server to renew OPEN_DOWNGRADE, READ, SETATTR, or WRITE) informs the server to renew
all of the leases for that client (i.e., all those sharing a given all of the leases for that client (i.e., all those sharing a given
client ID). In the latter case, the stateid must not be one of the client ID). In the latter case, the stateid must not be one of the
special stateids consisting of all bits 0 or all bits 1. special stateids (anonymous stateid or READ bypass stateid).
Note that if the client had restarted or rebooted, the client would Note that if the client had restarted or rebooted, the client would
not be making these requests without issuing the SETCLIENTID/ not be making these requests without issuing the SETCLIENTID/
SETCLIENTID_CONFIRM sequence. The use of the SETCLIENTID/ SETCLIENTID_CONFIRM sequence. The use of the SETCLIENTID/
SETCLIENTID_CONFIRM sequence (one that changes the client verifier) SETCLIENTID_CONFIRM sequence (one that changes the client verifier)
notifies the server to drop the locking state associated with the notifies the server to drop the locking state associated with the
client. SETCLIENTID/SETCLIENTID_CONFIRM never renews a lease. client. SETCLIENTID/SETCLIENTID_CONFIRM never renews a lease.
If the server has rebooted, the stateids (NFS4ERR_STALE_STATEID If the server has rebooted, the stateids (NFS4ERR_STALE_STATEID
error) or the client ID (NFS4ERR_STALE_CLIENTID error) will not be error) or the client ID (NFS4ERR_STALE_CLIENTID error) will not be
skipping to change at page 115, line 31 skipping to change at page 116, line 31
period the client may be forced to wait the remainder of the lease period the client may be forced to wait the remainder of the lease
period before obtaining new locks. period before obtaining new locks.
To minimize client delay upon restart, open and lock requests are To minimize client delay upon restart, open and lock requests are
associated with an instance of the client by a client supplied associated with an instance of the client by a client supplied
verifier. This verifier is part of the initial SETCLIENTID call made verifier. This verifier is part of the initial SETCLIENTID call made
by the client. The server returns a client ID as a result of the by the client. The server returns a client ID as a result of the
SETCLIENTID operation. The client then confirms the use of the SETCLIENTID operation. The client then confirms the use of the
client ID with SETCLIENTID_CONFIRM. The client ID in combination client ID with SETCLIENTID_CONFIRM. The client ID in combination
with an opaque owner field is then used by the client to identify the with an opaque owner field is then used by the client to identify the
open owner for OPEN. This chain of associations is then used to open-owner for OPEN. This chain of associations is then used to
identify all locks for a particular client. identify all locks for a particular client.
Since the verifier will be changed by the client upon each Since the verifier will be changed by the client upon each
initialization, the server can compare a new verifier to the verifier initialization, the server can compare a new verifier to the verifier
associated with currently held locks and determine that they do not associated with currently held locks and determine that they do not
match. This signifies the client's new instantiation and subsequent match. This signifies the client's new instantiation and subsequent
loss of locking state. As a result, the server is free to release loss of locking state. As a result, the server is free to release
all locks held which are associated with the old client ID which was all locks held which are associated with the old client ID which was
derived from the old verifier. derived from the old verifier.
skipping to change at page 118, line 22 skipping to change at page 119, line 22
or if it runs out of resources, the server MAY cause lease or if it runs out of resources, the server MAY cause lease
cancellation to occur at that time and henceforth return cancellation to occur at that time and henceforth return
NFS4ERR_EXPIRED when any of the stateids associated with the freed NFS4ERR_EXPIRED when any of the stateids associated with the freed
locks is used. If lease cancellation has not occurred and the server locks is used. If lease cancellation has not occurred and the server
receives a lock or I/O request that conflicts with one of the receives a lock or I/O request that conflicts with one of the
courtesy locks, the requirements are as follows: courtesy locks, the requirements are as follows:
o In the case of a courtesy lock which is not a delegation, it MUST o In the case of a courtesy lock which is not a delegation, it MUST
free the courtesy lock and grant the new request. free the courtesy lock and grant the new request.
o In the case of lock or IO request which conflicts with a o In the case of lock or I/O request which conflicts with a
delegation which is being held as courtesy lock, the server MAY delegation which is being held as courtesy lock, the server MAY
delay resolution of request but MUST NOT reject the request and delay resolution of request but MUST NOT reject the request and
MUST free the delegation and grant the new request eventually. MUST free the delegation and grant the new request eventually.
o In the case of a requests for a delegation which conflicts with a o In the case of a requests for a delegation which conflicts with a
delegation which is being held as courtesy lock, the server MAY delegation which is being held as a courtesy lock, the server MAY
grant the new request or not as it chooses, but if it grants the grant the new request or not as it chooses, but if it grants the
conflicting request, the delegation haled as courtesy lock MUST be conflicting request, the delegation held as a courtesy lock MUST
freed. be freed.
If the server does not reboot or cancel the lease before the network If the server does not reboot or cancel the lease before the network
partition is healed, when the original client tries to access a partition is healed, when the original client tries to access a
courtesy lock which was freed, the server SHOULD send back a courtesy lock which was freed, the server SHOULD send back a
NFS4ERR_BAD_STATEID to the client. If the client tries to access a NFS4ERR_BAD_STATEID to the client. If the client tries to access a
courtesy lock which was not freed, then the server SHOULD mark all of courtesy lock which was not freed, then the server SHOULD mark all of
the courtesy locks as implicitly being renewed. the courtesy locks as implicitly being renewed.
9.6.3.2. Lease Cancellation 9.6.3.2. Lease Cancellation
As a result of lease expiration, leases may be cancelled, either As a result of lease expiration, leases may be canceled, either
immediately upon expiration or subsequently, depending on the immediately upon expiration or subsequently, depending on the
occurrence of a conflicting lock or extension of the period of occurrence of a conflicting lock or extension of the period of
partition beyond what the server will tolerate. partition beyond what the server will tolerate.
When a lease is cancelled, all locking state associated with it is When a lease is canceled, all locking state associated with it is
freed and use of any the associated stateids will result in freed and use of any the associated stateids will result in
NFS4ERR_EXPIRED being returned. Similarly, use of the associated NFS4ERR_EXPIRED being returned. Similarly, use of the associated
clientid will result in NFS4ERR_EXPIRED being returned. clientid will result in NFS4ERR_EXPIRED being returned.
The client should recover from this situation by using SETCLIENTID The client should recover from this situation by using SETCLIENTID
followed by SETCLIENTID_CONFIRM, in order to establish a new followed by SETCLIENTID_CONFIRM, in order to establish a new
clientid. Once a lock is obtained using this clientid, a lease will clientid. Once a lock is obtained using this clientid, a lease will
be established. be established.
9.6.3.3. Client's Reaction to a Freed Lock 9.6.3.3. Client's Reaction to a Freed Lock
skipping to change at page 126, line 31 skipping to change at page 127, line 31
have occurred on the server and thus determine if it is possible that have occurred on the server and thus determine if it is possible that
a lease period expiration could have occurred. a lease period expiration could have occurred.
The third lock revocation event can occur as a result of The third lock revocation event can occur as a result of
administrative intervention within the lease period. While this is administrative intervention within the lease period. While this is
considered a rare event, it is possible that the server's considered a rare event, it is possible that the server's
administrator has decided to release or revoke a particular lock held administrator has decided to release or revoke a particular lock held
by the client. As a result of revocation, the client will receive an by the client. As a result of revocation, the client will receive an
error of NFS4ERR_ADMIN_REVOKED. In this instance the client may error of NFS4ERR_ADMIN_REVOKED. In this instance the client may
assume that only the state-owner's locks have been lost. The client assume that only the state-owner's locks have been lost. The client
notifies the lock holder appropriately. The client MUST NOT assume notifies the lock holder appropriately. The client cannot assume the
the lease period has been renewed as a result of a failed operation. lease period has been renewed as a result of a failed operation.
When the client determines the lease period may have expired, the When the client determines the lease period may have expired, the
client must mark all locks held for the associated lease as client must mark all locks held for the associated lease as
"unvalidated". This means the client has been unable to re-establish "unvalidated". This means the client has been unable to re-establish
or confirm the appropriate lock state with the server. As described or confirm the appropriate lock state with the server. As described
in Section 9.6, there are scenarios in which the server may grant in Section 9.6, there are scenarios in which the server may grant
conflicting locks after the lease period has expired for a client. conflicting locks after the lease period has expired for a client.
When it is possible that the lease period has expired, the client When it is possible that the lease period has expired, the client
must validate each lock currently held to ensure that a conflicting must validate each lock currently held to ensure that a conflicting
lock has not been granted. The client may accomplish this task by lock has not been granted. The client may accomplish this task by
issuing an I/O request, either a pending I/O or a zero-length read, issuing an I/O request; if there is no relevant I/O pending, a zero-
specifying the stateid associated with the lock in question. If the length read specifying the stateid associated with the lock in
response to the request is success, the client has validated all of question can be synthesised to trigger the renewal. If the response
the locks governed by that stateid and re-established the appropriate to the request is success, the client has validated all of the locks
state between itself and the server. governed by that stateid and re-established the appropriate state
between itself and the server.
If the I/O request is not successful, then one or more of the locks If the I/O request is not successful, then one or more of the locks
associated with the stateid was revoked by the server and the client associated with the stateid was revoked by the server and the client
must notify the owner. must notify the owner.
9.9. Share Reservations 9.9. Share Reservations
A share reservation is a mechanism to control access to a file. It A share reservation is a mechanism to control access to a file. It
is a separate and independent mechanism from byte-range locking. is a separate and independent mechanism from byte-range locking.
When a client opens a file, it issues an OPEN operation to the server When a client opens a file, it issues an OPEN operation to the server
skipping to change at page 127, line 44 skipping to change at page 128, line 44
const OPEN4_SHARE_DENY_NONE = 0x00000000; const OPEN4_SHARE_DENY_NONE = 0x00000000;
const OPEN4_SHARE_DENY_READ = 0x00000001; const OPEN4_SHARE_DENY_READ = 0x00000001;
const OPEN4_SHARE_DENY_WRITE = 0x00000002; const OPEN4_SHARE_DENY_WRITE = 0x00000002;
const OPEN4_SHARE_DENY_BOTH = 0x00000003; const OPEN4_SHARE_DENY_BOTH = 0x00000003;
9.10. OPEN/CLOSE Operations 9.10. OPEN/CLOSE Operations
To provide correct share semantics, a client MUST use the OPEN To provide correct share semantics, a client MUST use the OPEN
operation to obtain the initial filehandle and indicate the desired operation to obtain the initial filehandle and indicate the desired
access and what access, if any, to deny. Even if the client intends access and what access, if any, to deny. Even if the client intends
to use a stateid of all 0's or all 1's, it must still obtain the to use one of the special stateids (anonymous stateid or READ bypass
filehandle for the regular file with the OPEN operation so the stateid), it must still obtain the filehandle for the regular file
appropriate share semantics can be applied. Clients that do not have with the OPEN operation so the appropriate share semantics can be
a deny mode built into their programming interfaces for opening a applied. Clients that do not have a deny mode built into their
file should request a deny mode of OPEN4_SHARE_DENY_NONE. programming interfaces for opening a file should request a deny mode
of OPEN4_SHARE_DENY_NONE.
The OPEN operation with the CREATE flag, also subsumes the CREATE The OPEN operation with the CREATE flag, also subsumes the CREATE
operation for regular files as used in previous versions of the NFS operation for regular files as used in previous versions of the NFS
protocol. This allows a create with a share to be done atomically. protocol. This allows a create with a share to be done atomically.
The CLOSE operation removes all share reservations held by the open- The CLOSE operation removes all share reservations held by the open-
owner on that file. If byte-range locks are held, the client SHOULD owner on that file. If byte-range locks are held, the client SHOULD
release all locks before issuing a CLOSE. The server MAY free all release all locks before issuing a CLOSE. The server MAY free all
outstanding locks on CLOSE but some servers may not support the CLOSE outstanding locks on CLOSE but some servers may not support the CLOSE
of a file that still has byte-range locks held. The server MUST of a file that still has byte-range locks held. The server MUST
return failure, NFS4ERR_LOCKS_HELD, if any locks would exist after return failure, NFS4ERR_LOCKS_HELD, if any locks would exist after
the CLOSE. the CLOSE.
The LOOKUP operation will return a filehandle without establishing The LOOKUP operation will return a filehandle without establishing
any lock state on the server. Without a valid stateid, the server any lock state on the server. Without a valid stateid, the server
will assume the client has the least access. For example, if one will assume the client has the least access. For example, if one
client opened a file with OPEN4_SHARE_DENY_BOTH and another client client opened a file with OPEN4_SHARE_DENY_BOTH and another client
accesses the file via a filehandle obtained through LOOKUP, the accesses the file via a filehandle obtained through LOOKUP, the
second client could only read the file using the special read bypass second client could only read the file using the special READ bypass
stateid. The second client could not WRITE the file at all because stateid. The second client could not WRITE the file at all because
it would not have a valid stateid from OPEN and the special anonymous it would not have a valid stateid from OPEN and the special anonymous
stateid would not be allowed access. stateid would not be allowed access.
9.10.1. Close and Retention of State Information 9.10.1. Close and Retention of State Information
Since a CLOSE operation requests deallocation of a stateid, dealing Since a CLOSE operation requests deallocation of a stateid, dealing
with retransmission of the CLOSE, may pose special difficulties, with retransmission of the CLOSE, may pose special difficulties,
since the state information, which normally would be used to since the state information, which normally would be used to
determine the state of the open file being designated, might be determine the state of the open file being designated, might be
skipping to change at page 129, line 41 skipping to change at page 130, line 45
When multiple open files on the client are merged into a single open When multiple open files on the client are merged into a single open
file object on the server, the close of one of the open files (on the file object on the server, the close of one of the open files (on the
client) may necessitate change of the access and deny status of the client) may necessitate change of the access and deny status of the
open file on the server. This is because the union of the access and open file on the server. This is because the union of the access and
deny bits for the remaining opens may be smaller (i.e., a proper deny bits for the remaining opens may be smaller (i.e., a proper
subset) than previously. The OPEN_DOWNGRADE operation is used to subset) than previously. The OPEN_DOWNGRADE operation is used to
make the necessary change and the client should use it to update the make the necessary change and the client should use it to update the
server so that share reservation requests by other clients are server so that share reservation requests by other clients are
handled properly. The stateid returned has the same "other" field as handled properly. The stateid returned has the same "other" field as
that passed to the server. The "seqid" value in the returned stateid that passed to the server. The "seqid" value in the returned stateid
MUST be incremented, even in situations in which there is no change MUST be incremented (Section 9.1.4), even in situations in which
to the access and deny bits for the file. there has been no change to the access and deny bits for the file.
9.12. Short and Long Leases 9.12. Short and Long Leases
When determining the time period for the server lease, the usual When determining the time period for the server lease, the usual
lease tradeoffs apply. Short leases are good for fast server lease tradeoffs apply. Short leases are good for fast server
recovery at a cost of increased RENEW or READ (with zero length) recovery at a cost of increased RENEW or READ (with zero length)
requests. Longer leases are certainly kinder and gentler to servers requests. Longer leases are certainly kinder and gentler to servers
trying to handle very large numbers of clients. The number of RENEW trying to handle very large numbers of clients. The number of RENEW
requests drop in proportion to the lease time. The disadvantages of requests drop in proportion to the lease time. The disadvantages of
long leases are slower recovery after server failure (the server must long leases are slower recovery after server failure (the server must
skipping to change at page 133, line 21 skipping to change at page 134, line 23
When the client receives an NFS4ERR_MOVED error, the client can When the client receives an NFS4ERR_MOVED error, the client can
follow the normal process to obtain the new server information follow the normal process to obtain the new server information
(through the fs_locations attribute) and perform renewal of those (through the fs_locations attribute) and perform renewal of those
leases on the new server. If the server has not had state leases on the new server. If the server has not had state
transferred to it transparently, the client will receive either transferred to it transparently, the client will receive either
NFS4ERR_STALE_CLIENTID or NFS4ERR_STALE_STATEID from the new server, NFS4ERR_STALE_CLIENTID or NFS4ERR_STALE_STATEID from the new server,
as described above. The client can then recover state information as as described above. The client can then recover state information as
it does in the event of server failure. it does in the event of server failure.
9.14.4. Migration and the Lease_time Attribute 9.14.4. Migration and the lease_time Attribute
In order that the client may appropriately manage its leases in the In order that the client may appropriately manage its leases in the
case of migration, the destination server must establish proper case of migration, the destination server must establish proper
values for the lease_time attribute. values for the lease_time attribute.
When state is transferred transparently, that state should include When state is transferred transparently, that state should include
the correct value of the lease_time attribute. The lease_time the correct value of the lease_time attribute. The lease_time
attribute on the destination server must never be less than that on attribute on the destination server must never be less than that on
the source since this would result in premature expiration of leases the source since this would result in premature expiration of leases
granted by the source server. Upon migration in which state is granted by the source server. Upon migration in which state is
skipping to change at page 136, line 31 skipping to change at page 137, line 37
has the information necessary to grant or deny the second client's has the information necessary to grant or deny the second client's
request. request.
At the time the client receives a delegation recall, it may have At the time the client receives a delegation recall, it may have
substantial state that needs to be flushed to the server. Therefore, substantial state that needs to be flushed to the server. Therefore,
the server should allow sufficient time for the delegation to be the server should allow sufficient time for the delegation to be
returned since it may involve numerous RPCs to the server. If the returned since it may involve numerous RPCs to the server. If the
server is able to determine that the client is diligently flushing server is able to determine that the client is diligently flushing
state to the server as a result of the recall, the server MAY extend state to the server as a result of the recall, the server MAY extend
the usual time allowed for a recall. However, the time allowed for the usual time allowed for a recall. However, the time allowed for
recall completion SHOULD NOT be unbounded. recall completion should not be unbounded.
An example of this is when responsibility to mediate opens on a given An example of this is when responsibility to mediate opens on a given
file is delegated to a client (see Section 10.4). The server will file is delegated to a client (see Section 10.4). The server will
not know what opens are in effect on the client. Without this not know what opens are in effect on the client. Without this
knowledge the server will be unable to determine if the access and knowledge the server will be unable to determine if the access and
deny state for the file allows any particular open until the deny state for the file allows any particular open until the
delegation for the file has been returned. delegation for the file has been returned.
A client failure or a network partition can result in failure to A client failure or a network partition can result in failure to
respond to a recall callback. In this case, the server will revoke respond to a recall callback. In this case, the server will revoke
skipping to change at page 138, line 6 skipping to change at page 139, line 14
A server MAY support a claim type of CLAIM_DELEGATE_PREV, but if it A server MAY support a claim type of CLAIM_DELEGATE_PREV, but if it
does, it MUST NOT remove delegations upon SETCLIENTID_CONFIRM and does, it MUST NOT remove delegations upon SETCLIENTID_CONFIRM and
instead MUST make them available for client reclaim using instead MUST make them available for client reclaim using
CLAIM_DELEGATE_PREV. The server MUST NOT remove the delegations CLAIM_DELEGATE_PREV. The server MUST NOT remove the delegations
until either the client does a DELEGPURGE, or one lease period has until either the client does a DELEGPURGE, or one lease period has
elapsed from the time the later of the SETCLIENTID_CONFIRM or the elapsed from the time the later of the SETCLIENTID_CONFIRM or the
last successful CLAIM_DELEGATE_PREV reclaim. last successful CLAIM_DELEGATE_PREV reclaim.
Note that the requirement stated above is not meant to imply that Note that the requirement stated above is not meant to imply that
when the client is no longer obliged, as required above, to retain when the server is no longer obliged, as required above, to retain
delegation information, that it should necessarily dispose of it. delegation information, that it should necessarily dispose of it.
Some specific cases are: Some specific cases are:
o When the period is terminated by the occurrence of DELEGPURGE, o When the period is terminated by the occurrence of DELEGPURGE,
deletion of unreclaimed delegations is appropriate and desirable. deletion of unreclaimed delegations is appropriate and desirable.
o When the period is terminated by a lease period elapsing without a o When the period is terminated by a lease period elapsing without a
successful CLAIM_DELEGATE_PREV reclaim, and that situation appears successful CLAIM_DELEGATE_PREV reclaim, and that situation appears
to be the result of a network partition (i.e., lease expiration to be the result of a network partition (i.e., lease expiration
has occurred), a server's lease expiration approach, possibly has occurred), a server's lease expiration approach, possibly
skipping to change at page 140, line 28 skipping to change at page 141, line 35
server should recall delegations in this class in preference to server should recall delegations in this class in preference to
keeping them active without persistent storage recording. keeping them active without persistent storage recording.
When a network partition occurs, delegations are subject to freeing When a network partition occurs, delegations are subject to freeing
by the server when the lease renewal period expires. This is similar by the server when the lease renewal period expires. This is similar
to the behavior for locks and share reservations, and, as for locks to the behavior for locks and share reservations, and, as for locks
and share reservations it may be modified by support for "courtesy and share reservations it may be modified by support for "courtesy
locks" in which locks are not freed in the absence of a conflicting locks" in which locks are not freed in the absence of a conflicting
lock request. Whereas, for locks and share reservations, freeing of lock request. Whereas, for locks and share reservations, freeing of
locks will occur immediately upon the appearance of a conflicting locks will occur immediately upon the appearance of a conflicting
request, for delegations, the server may institute period during request, for delegations, the server MAY institute period during
which conflicting requests are held off. Eventually the occurrence which conflicting requests are held off. Eventually the occurrence
of a conflicting request from another client will cause revocation of of a conflicting request from another client will cause revocation of
the delegation. the delegation.
A loss of the callback path (e.g., by later network configuration A loss of the callback path (e.g., by later network configuration
change) will have a similar effect in that it can also result in change) will have a similar effect in that it can also result in
revocation of a delegation A recall request will fail and revocation revocation of a delegation A recall request will fail and revocation
of the delegation will result. of the delegation will result.
A client normally finds out about revocation of a delegation when it A client normally finds out about revocation of a delegation when it
skipping to change at page 142, line 15 skipping to change at page 143, line 27
o First, cached data present on a client must be revalidated after o First, cached data present on a client must be revalidated after
doing an OPEN. Revalidating means that the client fetches the doing an OPEN. Revalidating means that the client fetches the
change attribute from the server, compares it with the cached change attribute from the server, compares it with the cached
change attribute, and if different, declares the cached data (as change attribute, and if different, declares the cached data (as
well as the cached attributes) as invalid. This is to ensure that well as the cached attributes) as invalid. This is to ensure that
the data for the OPENed file is still correctly reflected in the the data for the OPENed file is still correctly reflected in the
client's cache. This validation must be done at least when the client's cache. This validation must be done at least when the
client's OPEN operation includes DENY=WRITE or BOTH thus client's OPEN operation includes DENY=WRITE or BOTH thus
terminating a period in which other clients may have had the terminating a period in which other clients may have had the
opportunity to open the file with WRITE access. Clients may opportunity to open the file with WRITE access. Clients may
choose to do the revalidation more often (such as an OPENs choose to do the revalidation more often (such as at OPENs
specifying DENY=NONE) to parallel the NFSv3 protocol's practice specifying DENY=NONE) to parallel the NFSv3 protocol's practice
for the benefit of users assuming this degree of cache for the benefit of users assuming this degree of cache
revalidation. revalidation.
Since the change attribute is updated for data and metadata Since the change attribute is updated for data and metadata
modifications, some client implementers may be tempted to use the modifications, some client implementers may be tempted to use the
time_modify attribute and not the change attribute to validate time_modify attribute and not the change attribute to validate
cached data, so that metadata changes do not spuriously invalidate cached data, so that metadata changes do not spuriously invalidate
clean data. The implementer is cautioned in this approach. The clean data. The implementer is cautioned against this approach.
change attribute is guaranteed to change for each update to the The change attribute is guaranteed to change for each update to
file, whereas time_modify is guaranteed to change only at the the file, whereas time_modify is guaranteed to change only at the
granularity of the time_delta attribute. Use by the client's data granularity of the time_delta attribute. Use by the client's data
cache validation logic of time_modify and not the change attribute cache validation logic of time_modify and not the change attribute
runs the risk of the client incorrectly marking stale data as runs the risk of the client incorrectly marking stale data as
valid. valid.
o Second, modified data must be flushed to the server before closing o Second, modified data must be flushed to the server before closing
a file OPENed for write. This is complementary to the first rule. a file OPENed for write. This is complementary to the first rule.
If the data is not flushed at CLOSE, the revalidation done after If the data is not flushed at CLOSE, the revalidation done after
the client OPENs a file is unable to achieve its purpose. The the client OPENs a file is unable to achieve its purpose. The
other aspect to flushing the data before close is that the data other aspect to flushing the data before close is that the data
skipping to change at page 148, line 43 skipping to change at page 149, line 49
"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 that did not originate from this write and thus no write has occurred that did not originate from this
client. Similarly, when closing a file opened for write and if client. Similarly, when closing a file opened for write and if
OPEN_DELEGATE_WRITE delegation is in effect, the data written does OPEN_DELEGATE_WRITE delegation is in effect, the data written does
not have to be flushed to the server until the open delegation is not have to be flushed to the server until the open delegation is
recalled. The continued endurance of the open delegation provides a recalled. The continued endurance of the open delegation provides a
guarantee that no open and thus no read or write has been done by guarantee that no open and thus no read or write has been done by
another client. 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 (anonymous and READ bypass stateids) are treated as the
type of OPEN. This refers to the READs and WRITEs that use the functional equivalents of a corresponding type of OPEN. READs and
special stateids consisting of all zero bits or all one bits. WRITEs done with an anonymous stateid done by another client will
Therefore, READs or WRITEs with a special stateid done by another force the server to recall a OPEN_DELEGATE_WRITE delegation. A WRITE
client will force the server to recall a OPEN_DELEGATE_WRITE with an anonymous stateid done by another client will force a recall
delegation. A WRITE with a special stateid done by another client of OPEN_DELEGATE_READ delegations. The handling of a READ bypass
will force a recall of OPEN_DELEGATE_READ delegations. stateid is identical except that a READ done with a READ bypass
stateid will not force a recall of an OPEN_DELEGATE_READ delegation.
With delegations, a client is able to avoid writing data to the With delegations, a client is able to avoid writing data to the
server when the CLOSE of a file is serviced. The file close system server when the CLOSE of a file is serviced. The file close system
call is the usual point at which the client is notified of a lack of call is the usual point at which the client is notified of a lack of
stable storage for the modified file data generated by the stable storage for the modified file data generated by the
application. At the close, file data is written to the server and application. At the close, file data is written to the server and
through normal accounting the server is able to determine if the through normal accounting the server is able to determine if the
available file system space for the data has been exceeded (i.e., available file system space for the data has been exceeded (i.e.,
server returns NFS4ERR_NOSPC or NFS4ERR_DQUOT). This accounting server returns NFS4ERR_NOSPC or NFS4ERR_DQUOT). This accounting
includes quotas. The introduction of delegations requires that a includes quotas. The introduction of delegations requires that a
skipping to change at page 149, line 38 skipping to change at page 150, line 45
the server may grant OPEN_DELEGATE_WRITE delegations with very the server may grant OPEN_DELEGATE_WRITE delegations with very
restrictive space limitations. The limitations may be defined in a restrictive space limitations. The limitations may be defined in a
way that will always force modified data to be flushed to the server way that will always force modified data to be flushed to the server
on close. on close.
With respect to authentication, flushing modified data to the server With respect to authentication, flushing modified data to the server
after a CLOSE has occurred may be problematic. For example, the user after a CLOSE has occurred may be problematic. For example, the user
of the application may have logged off the client and unexpired of the application may have logged off the client and unexpired
authentication credentials may not be present. In this case, the authentication credentials may not be present. In this case, the
client may need to take special care to ensure that local unexpired client may need to take special care to ensure that local unexpired
credentials will in fact be available. This may be accomplished by credentials will in fact be available. One way that this may be
tracking the expiration time of credentials and flushing data well in accomplished by tracking the expiration time of credentials and
advance of their expiration or by making private copies of flushing data well in advance of their expiration.
credentials to assure their availability when needed.
10.4.2. Open Delegation and File Locks 10.4.2. Open Delegation and File Locks
When a client holds a OPEN_DELEGATE_WRITE delegation, lock operations When a client holds a OPEN_DELEGATE_WRITE delegation, lock operations
may be performed locally. This includes those required for mandatory may be performed locally. This includes those required for mandatory
file locking. This can be done since the delegation implies that file locking. This can be done since the delegation implies that
there can be no conflicting locks. Similarly, all of the there can be no conflicting locks. Similarly, all of the
revalidations that would normally be associated with obtaining locks revalidations that would normally be associated with obtaining locks
and the flushing of data associated with the releasing of locks need and the flushing of data associated with the releasing of locks need
not be done. not be done.
skipping to change at page 153, line 6 skipping to change at page 154, line 16
requested, but make sure size comes from what CB_GETATTR returned. requested, but make sure size comes from what CB_GETATTR returned.
The server would not update the file's metadata with the client's The server would not update the file's metadata with the client's
modified size. modified size.
In the case that the file attribute size is different than the In the case that the file attribute size is different than the
server's current value, the server treats this as a modification server's current value, the server treats this as a modification
regardless of the value of the change attribute retrieved via regardless of the value of the change attribute retrieved via
CB_GETATTR and responds to the second client as in the last step. CB_GETATTR and responds to the second client as in the last step.
This methodology resolves issues of clock differences between client This methodology resolves issues of clock differences between client
and server and other scenarios where the use of CB_GETATTR break and server and other scenarios where the use of CB_GETATTR breaks
down. down.
It should be noted that the server is under no obligation to use It should be noted that the server is under no obligation to use
CB_GETATTR and therefore the server MAY simply recall the delegation CB_GETATTR and therefore the server MAY simply recall the delegation
to avoid its use. to avoid its use.
10.4.4. Recall of Open Delegation 10.4.4. Recall of Open Delegation
The following events necessitate recall of an open delegation: The following events necessitate recall of an open delegation:
skipping to change at page 157, line 25 skipping to change at page 158, line 38
client. In the case of modified data existing in the client's cache, client. In the case of modified data existing in the client's cache,
that data must be removed from the client without it being written to that data must be removed from the client without it being written to
the server. As mentioned, the assumptions made by the client are no the server. As mentioned, the assumptions made by the client are no
longer valid at the point when a lock or delegation has been revoked. longer valid at the point when a lock or delegation has been revoked.
For example, another client may have been granted a conflicting lock For example, another client may have been granted a conflicting lock
after the revocation of the lock at the first client. Therefore, the after the revocation of the lock at the first client. Therefore, the
data within the lock range may have been modified by the other data within the lock range may have been modified by the other
client. Obviously, the first client is unable to guarantee to the client. Obviously, the first client is unable to guarantee to the
application what has occurred to the file in the case of revocation. application what has occurred to the file in the case of revocation.
Notification to a lock owner will in many cases consist of simply Notification to a lock-owner will in many cases consist of simply
returning an error on the next and all subsequent READs/WRITEs to the returning an error on the next and all subsequent READs/WRITEs to the
open file or on the close. Where the methods available to a client open file or on the close. Where the methods available to a client
make such notification impossible because errors for certain make such notification impossible because errors for certain
operations may not be returned, more drastic action such as signals operations may not be returned, more drastic action such as signals
or process termination may be appropriate. The justification for or process termination may be appropriate. The justification for
this is that an invariant for which an application depends on may be this is that an invariant for which an application depends on may be
violated. Depending on how errors are typically treated for the violated. Depending on how errors are typically treated for the
client operating environment, further levels of notification client operating environment, further levels of notification
including logging, console messages, and GUI pop-ups may be including logging, console messages, and GUI pop-ups may be
appropriate. appropriate.
skipping to change at page 160, line 36 skipping to change at page 162, line 4
occurs and the file is read (or if the block does not exist in the occurs and the file is read (or if the block does not exist in the
file, the block is allocated and then instantiated in the file, the block is allocated and then instantiated in the
application's address space). application's address space).
As long as each memory mapped access to the file requires a page As long as each memory mapped access to the file requires a page
fault, the relevant attributes of the file that are used to detect fault, the relevant attributes of the file that are used to detect
access and modification (time_access, time_metadata, time_modify, and access and modification (time_access, time_metadata, time_modify, and
change) will be updated. However, in many operating environments, change) will be updated. However, in many operating environments,
when page faults are not required these attributes will not be when page faults are not required these attributes will not be
updated on reads or updates to the file via memory access (regardless updated on reads or updates to the file via memory access (regardless
of whether the file is a local file or is being access remotely). A of whether the file is a local file or is being accessed remotely).
client or server MAY fail to update attributes of a file that is A client or server MAY fail to update attributes of a file that is
being accessed via memory mapped I/O. This has several implications: being accessed via memory mapped I/O. This has several implications:
o If there is an application on the server that has memory mapped a o If there is an application on the server that has memory mapped a
file that a client is also accessing, the client may not be able file that a client is also accessing, the client may not be able
to get a consistent value of the change attribute to determine to get a consistent value of the change attribute to determine
whether its cache is stale or not. A server that knows that the whether its cache is stale or not. A server that knows that the
file is memory mapped could always pessimistically return updated file is memory mapped could always pessimistically return updated
values for change so as to force the application to always get the values for change so as to force the application to always get the
most up to date data and metadata for the file. However, due to most up to date data and metadata for the file. However, due to
the negative performance implications of this, such behavior is the negative performance implications of this, such behavior is
skipping to change at page 167, line 40 skipping to change at page 169, line 6
with normalization-related handling described in Section 12.4. with normalization-related handling described in Section 12.4.
These are best described as "UTF-8-only servers". These are best described as "UTF-8-only servers".
o Servers which do not limit file component names to UTF-8 strings o Servers which do not limit file component names to UTF-8 strings
are very common and are necessary to deal with clients/ are very common and are necessary to deal with clients/
applications not oriented to the use of UTF-8. Such servers applications not oriented to the use of UTF-8. Such servers
ignore normalization-related issues and there is no way for them ignore normalization-related issues and there is no way for them
to implement either normalization or representation-independent to implement either normalization or representation-independent
lookups. These are best described as "UTF-8-unaware servers" lookups. These are best described as "UTF-8-unaware servers"
since they treat file component names as uninterpreted strings of since they treat file component names as uninterpreted strings of
bytes and have no knowledge of the characters represented. Such bytes and have no knowledge of the characters represented. See
servers ignore normalization-related issues and there is no way Section 12.7 for details.
for them to implement either normalization or representation-
independent lookups. See Section 12.7 for details.
o It is possible for a server to allow component names which are not o It is possible for a server to allow component names which are not
valid UTF-8, while still being aware of the structure of UTF-8 valid UTF-8, while still being aware of the structure of UTF-8
strings. Such servers could implement either normalization or strings. Such servers could implement either normalization or
representation-independent lookups, but apply those techniques representation-independent lookups, but apply those techniques
only to valid UTF-8 strings. Such servers are not common, but it only to valid UTF-8 strings. Such servers are not common, but it
is possible to configure at least one known server to have this is possible to configure at least one known server to have this
behavior. This behavior SHOULD NOT be used due to the possibility behavior. This behavior SHOULD NOT be used due to the possibility
that a filename using one character set may, by coincidence, have that a filename using one character set may, by coincidence, have
the appearance of a UTF-8 filename; the results of UTF-8 the appearance of a UTF-8 filename; the results of UTF-8
normalization or representation-independent lookups are unlikely normalization or representation-independent lookups are unlikely
to be correct in all cases with respect to the other character to be correct in all cases with respect to the other character
set. set.
12.4. String Encoding 12.4. String Encoding
Strings that potentially contain characters outside the ASCII range Strings that potentially contain characters outside the ASCII range
[RFC20] are generally represented in NFSv4 using the UTF-8 encoding [RFC20] are generally represented in NFSv4 using the UTF-8 encoding
[RFC3629] of Unicode [UNICODE]. See [RFC2279] for precise encoding [RFC3629] of Unicode [UNICODE]. See [RFC3629] for precise encoding
and decoding rules. and decoding rules.
Some details of the protocol treatment depend on the type of string: Some details of the protocol treatment depend on the type of string:
o For strings which are component names, the preferred encoding for o For strings which are component names, the preferred encoding for
any non-ASCII characters is the UTF-8 representation of Unicode. any non-ASCII characters is the UTF-8 representation of Unicode.
In many cases, clients have no knowledge of the encoding being In many cases, clients have no knowledge of the encoding being
used, with the encoding done at user-level under control of a per- used, with the encoding done at user-level under control of a per-
process locale specification. As a result, it may be impossible process locale specification. As a result, it may be impossible
for the NFSv4 client to enforce use of UTF-8. Use of non-UTF-8 for the NFSv4 client to enforce use of UTF-8. Use of non-UTF-8
encodings can be problematic since it may interfere with access to encodings can be problematic since it may interfere with access to
files stored using other forms of name encoding. Also, files stored using other forms of name encoding. Also,
normalization-related processing (see Section 12.5) of a string normalization-related processing (see Section 12.5) of a string
not encoded in UTF-8 could result in inappropriate name not encoded in UTF-8 could result in inappropriate name
modification or aliasing. In cases in which one has a non-UT8- modification or aliasing. In cases in which one has a non-UTF8
name that accidentally conforms to UTF-8 rules, substitution of encoded name that accidentally conforms to UTF-8 rules,
canonically equivalent strings can change the non-UTF-8 encoded substitution of canonically equivalent strings can change the non-
name drastically. UTF-8 encoded name drastically.
The kinds of modification and aliasing mentioned here can lead to The kinds of modification and aliasing mentioned here can lead to
both false negatives and false positives depending on the strings both false negatives and false positives depending on the strings
in question, which can result in security issues such as elevation in question, which can result in security issues such as elevation
of privilege and denial of service (see [RFC6943] for further of privilege and denial of service (see [RFC6943] for further
discussion). discussion).
o For strings based on domain names, non-ASCII characters MUST be o For strings based on domain names, non-ASCII characters MUST be
represented using the UTF-8 encoding of Unicode, and additional represented using the UTF-8 encoding of Unicode, and additional
string format restrictions apply. See Section 12.6 for details. string format restrictions apply. See Section 12.6 for details.
skipping to change at page 169, line 28 skipping to change at page 170, line 39
matching and may or may not preserve the character case when storing matching and may or may not preserve the character case when storing
file names. The protocol does not mandate a particular behavior but file names. The protocol does not mandate a particular behavior but
allows for a range of useful behaviors. allows for a range of useful behaviors.
The NFS version 4 protocol does not mandate the use of a particular The NFS version 4 protocol does not mandate the use of a particular
normalization form at this time. A subsequent minor version of the normalization form at this time. A subsequent minor version of the
NFSv4 protocol might specify a particular normalization form. NFSv4 protocol might specify a particular normalization form.
Therefore, the server and client can expect that they may receive Therefore, the server and client can expect that they may receive
unnormalized characters within protocol requests and responses. If unnormalized characters within protocol requests and responses. If
the operating environment requires normalization, then the the operating environment requires normalization, then the
implementation must normalize the various UTF-8 encoded strings implementation will need to normalize the various UTF-8 encoded
within the protocol before presenting the information to an strings within the protocol before presenting the information to an
application (at the client) or local file system (at the server). application (at the client) or local file system (at the server).
Server implementations MAY normalize file names to conform to a Server implementations MAY normalize file names to conform to a
particular normalization form before using the resulting string when particular normalization form before using the resulting string when
looking up or creating a file. Servers MAY also perform looking up or creating a file. Servers MAY also perform
normalization-insensitive string comparisons without modifying name normalization-insensitive string comparisons without modifying the
to match a particular normalization form. Except in cases in which names to match a particular normalization form. Except in cases in
component names are excluded from normalization-related handling which component names are excluded from normalization-related
because they are not valid UTF-8 strings, a server MUST make the same handling because they are not valid UTF-8 strings, a server MUST make
choice (as to whether to normalize or not, the target form of the same choice (as to whether to normalize or not, the target form
normalization and whether to do normalization-insensitive string of normalization and whether to do normalization-insensitive string
comparisons) in the same way for all accesses to a particular file comparisons) in the same way for all accesses to a particular file
system. Servers SHOULD NOT reject a file name because it does not system. Servers SHOULD NOT reject a file name because it does not
conform to a particular normalization form as this may deny access to conform to a particular normalization form as this may deny access to
clients that use a different normalization form. clients that use a different normalization form.
12.6. Types with Processing Defined by Other Internet Areas 12.6. Types with Processing Defined by Other Internet Areas
There are two types of strings that NFSv4 deals with that are based There are two types of strings that NFSv4 deals with that are based
on domain names. Processing of such strings is defined by other on domain names. Processing of such strings is defined by other
Internet standards, and hence the processing behavior for such Internet standards, and hence the processing behavior for such
skipping to change at page 170, line 22 skipping to change at page 171, line 33
o Principal suffixes which are used to denote sets of users and o Principal suffixes which are used to denote sets of users and
groups, and are in the form of domain names. groups, and are in the form of domain names.
The general rules for handling all of these domain-related strings The general rules for handling all of these domain-related strings
are similar and independent of the role of the sender or receiver as are similar and independent of the role of the sender or receiver as
client or server although the consequences of failure to obey these client or server although the consequences of failure to obey these
rules may be different for client or server. The server can report rules may be different for client or server. The server can report
errors when it is sent invalid strings, whereas the client will errors when it is sent invalid strings, whereas the client will
simply ignore invalid string or use a default value in their place. simply ignore invalid string or use a default value in their place.
The string sent SHOULD be in the form of a U-label. If that is The string sent SHOULD be in the form of one or more U-labels as
impractical, it can instead be in the form of one or more A-labels or defined by [RFC5890]. If that is impractical, it can instead be in
a UTF-8 domain name that is not a properly formatted U-label. The the form of one or more LDH labels [RFC5890] or a UTF-8 domain name
that contains labels that are not properly formatted U-labels. The
receiver needs to be able to accept domain and server names in any of receiver needs to be able to accept domain and server names in any of
the formats allowed. The server MUST reject, using the error the formats allowed. The server MUST reject, using the error
NFS4ERR_INVAL, a string which is not valid UTF-8 or which begins with NFS4ERR_INVAL, a string that is not valid UTF-8, or that contains an
"xn--" and violates the rules for a valid A-label. ASCII label that is not a valid LDH label, or that contains an XN-
label (begins with "xn--") for which the characters after "xn--" are
not valid output of the Punycode algorithm [RFC3492].
When a domain string is part of id@domain or group@domain, there are When a domain string is part of id@domain or group@domain, there are
two possible approaches: two possible approaches:
1. The server treats the domain string as a U-label (see [RFC5890] 1. The server treats the domain string as a series of U-labels. In
This happens if the domain string is an A-label (or is a UTF-8- cases where the domain string is a series of A-labels or NR-LDH
encoded string which is not a U-label) and the server converts labels, it converts them to U-labels using the Punycode algorithm
the domain string to the corresponding U-label, using the [RFC3492]. In cases where the domain string is series of other
functions ToUnicode(domain) or ToUnicode(ToASCII(domain)). As a sorts of LDH labels, the server can use the ToUnicode function
result, the domain string returned within a userid on a GETATTR defined in [RFC3490] to convert the string to a series of labels
may not match that sent when the userid is set using SETATTR, that generally conform to the U-label syntax. In cases where the
although when this happens, the domain will be in the form of an domain string is a UTF-8 string that contains non-U-labels, the
U-label. server can attempt to use to ToASCII function defined in
[RFC3490] and then the ToUnicode function on the string to
convert it to a series of labels that generally conform to the
U-label syntax. As a result, the domain string returned within a
userid on a GETATTR may not match that sent when the userid is
set using SETATTR, although when this happens, the domain will be
in the form that generally conform to the U-label syntax.
2. The server does not attempt to treat the domain string as a 2. The server does not attempt to treat the domain string as a
U-label; specifically, it does not map a domain string which is series of U-labels; specifically, it does not map a domain string
not a U-label into a U-label using the ToUnicode function as which is not a U-label into a U-label using the methods described
described above. As a result, the domain string returned on a above. As a result, the domain string returned on a GETATTR of
GETATTR of the userid MUST be the same as that used when setting the userid MUST be the same as that used when setting the userid
the userid by the SETATTR. by the SETATTR.
A server SHOULD use the first method. A server SHOULD use the first method.
For VERIFY and NVERIFY, additional string processing requirements For VERIFY and NVERIFY, additional string processing requirements
apply to verification of the owner and owner_group attributes, see apply to verification of the owner and owner_group attributes, see
Section 5.9. Section 5.9.
12.7. UTF-8 Related Errors 12.7. UTF-8 Related Errors
Where the client sends an invalid UTF-8 string, the server MAY return Where the client sends an invalid UTF-8 string, the server MAY return
skipping to change at page 172, line 49 skipping to change at page 174, line 24
13.1. Error Definitions 13.1. Error Definitions
Protocol Error Definitions Protocol Error Definitions
+-----------------------------+--------+-------------------+ +-----------------------------+--------+-------------------+
| Error | Number | Description | | Error | Number | Description |
+-----------------------------+--------+-------------------+ +-----------------------------+--------+-------------------+
| NFS4_OK | 0 | Section 13.1.3.1 | | NFS4_OK | 0 | Section 13.1.3.1 |
| NFS4ERR_ACCESS | 13 | Section 13.1.6.1 | | NFS4ERR_ACCESS | 13 | Section 13.1.6.1 |
| NFS4ERR_ATTRNOTSUPP | 10032 | Section 13.1.11.1 |
| NFS4ERR_ADMIN_REVOKED | 10047 | Section 13.1.5.1 | | NFS4ERR_ADMIN_REVOKED | 10047 | Section 13.1.5.1 |
| NFS4ERR_ATTRNOTSUPP | 10032 | Section 13.1.11.1 |
| NFS4ERR_BADCHAR | 10040 | Section 13.1.7.1 | | NFS4ERR_BADCHAR | 10040 | Section 13.1.7.1 |
| NFS4ERR_BADHANDLE | 10001 | Section 13.1.2.1 | | NFS4ERR_BADHANDLE | 10001 | Section 13.1.2.1 |
| NFS4ERR_BADNAME | 10041 | Section 13.1.7.2 | | NFS4ERR_BADNAME | 10041 | Section 13.1.7.2 |
| NFS4ERR_BADOWNER | 10039 | Section 13.1.11.2 | | NFS4ERR_BADOWNER | 10039 | Section 13.1.11.2 |
| NFS4ERR_BADTYPE | 10007 | Section 13.1.4.1 | | NFS4ERR_BADTYPE | 10007 | Section 13.1.4.1 |
| NFS4ERR_BADXDR | 10036 | Section 13.1.1.1 | | NFS4ERR_BADXDR | 10036 | Section 13.1.1.1 |
| NFS4ERR_BAD_COOKIE | 10003 | Section 13.1.1.2 | | NFS4ERR_BAD_COOKIE | 10003 | Section 13.1.1.2 |
| NFS4ERR_BAD_RANGE | 10042 | Section 13.1.8.1 | | NFS4ERR_BAD_RANGE | 10042 | Section 13.1.8.1 |
| NFS4ERR_BAD_SEQID | 10026 | Section 13.1.8.2 | | NFS4ERR_BAD_SEQID | 10026 | Section 13.1.8.2 |
| NFS4ERR_BAD_STATEID | 10025 | Section 13.1.5.2 | | NFS4ERR_BAD_STATEID | 10025 | Section 13.1.5.2 |
| NFS4ERR_CB_PATH_DOWN | 10048 | Section 13.1.12.1 |
| NFS4ERR_CLID_INUSE | 10017 | Section 13.1.10.1 | | NFS4ERR_CLID_INUSE | 10017 | Section 13.1.10.1 |
| NFS4ERR_DEADLOCK | 10045 | Section 13.1.8.3 | | NFS4ERR_DEADLOCK | 10045 | Section 13.1.8.3 |
| NFS4ERR_DELAY | 10008 | Section 13.1.1.3 | | NFS4ERR_DELAY | 10008 | Section 13.1.1.3 |
| NFS4ERR_DENIED | 10010 | Section 13.1.8.4 | | NFS4ERR_DENIED | 10010 | Section 13.1.8.4 |
| NFS4ERR_DQUOT | 69 | Section 13.1.4.2 | | NFS4ERR_DQUOT | 69 | Section 13.1.4.2 |
| NFS4ERR_EXIST | 17 | Section 13.1.4.3 | | NFS4ERR_EXIST | 17 | Section 13.1.4.3 |
| NFS4ERR_EXPIRED | 10011 | Section 13.1.5.3 | | NFS4ERR_EXPIRED | 10011 | Section 13.1.5.3 |
| NFS4ERR_FBIG | 27 | Section 13.1.4.4 | | NFS4ERR_FBIG | 27 | Section 13.1.4.4 |
| NFS4ERR_FHEXPIRED | 10014 | Section 13.1.2.2 | | NFS4ERR_FHEXPIRED | 10014 | Section 13.1.2.2 |
| NFS4ERR_FILE_OPEN | 10046 | Section 13.1.4.5 | | NFS4ERR_FILE_OPEN | 10046 | Section 13.1.4.5 |
skipping to change at page 174, line 7 skipping to change at page 175, line 31
| NFS4ERR_OPENMODE | 10038 | Section 13.1.8.9 | | NFS4ERR_OPENMODE | 10038 | Section 13.1.8.9 |
| NFS4ERR_OP_ILLEGAL | 10044 | Section 13.1.3.3 | | NFS4ERR_OP_ILLEGAL | 10044 | Section 13.1.3.3 |
| NFS4ERR_PERM | 1 | Section 13.1.6.2 | | NFS4ERR_PERM | 1 | Section 13.1.6.2 |
| NFS4ERR_RECLAIM_BAD | 10034 | Section 13.1.9.3 | | NFS4ERR_RECLAIM_BAD | 10034 | Section 13.1.9.3 |
| NFS4ERR_RECLAIM_CONFLICT | 10035 | Section 13.1.9.4 | | NFS4ERR_RECLAIM_CONFLICT | 10035 | Section 13.1.9.4 |
| NFS4ERR_RESOURCE | 10018 | Section 13.1.3.4 | | NFS4ERR_RESOURCE | 10018 | Section 13.1.3.4 |
| NFS4ERR_RESTOREFH | 10030 | Section 13.1.4.12 | | NFS4ERR_RESTOREFH | 10030 | Section 13.1.4.12 |
| NFS4ERR_ROFS | 30 | Section 13.1.4.13 | | NFS4ERR_ROFS | 30 | Section 13.1.4.13 |
| NFS4ERR_SAME | 10009 | Section 13.1.11.4 | | NFS4ERR_SAME | 10009 | Section 13.1.11.4 |
| NFS4ERR_SERVERFAULT | 10006 | Section 13.1.1.6 | | NFS4ERR_SERVERFAULT | 10006 | Section 13.1.1.6 |
| NFS4ERR_SHARE_DENIED | 10015 | Section 13.1.8.10 |
| NFS4ERR_STALE | 70 | Section 13.1.2.7 | | NFS4ERR_STALE | 70 | Section 13.1.2.7 |
| NFS4ERR_STALE_CLIENTID | 10022 | Section 13.1.10.2 | | NFS4ERR_STALE_CLIENTID | 10022 | Section 13.1.10.2 |
| NFS4ERR_STALE_STATEID | 10023 | Section 13.1.5.6 | | NFS4ERR_STALE_STATEID | 10023 | Section 13.1.5.6 |
| NFS4ERR_SYMLINK | 10029 | Section 13.1.2.8 | | NFS4ERR_SYMLINK | 10029 | Section 13.1.2.8 |
| NFS4ERR_TOOSMALL | 10005 | Section 13.1.1.7 | | NFS4ERR_TOOSMALL | 10005 | Section 13.1.1.7 |
| NFS4ERR_WRONGSEC | 10016 | Section 13.1.6.3 | | NFS4ERR_WRONGSEC | 10016 | Section 13.1.6.3 |
| NFS4ERR_XDEV | 18 | Section 13.1.4.14 | | NFS4ERR_XDEV | 18 | Section 13.1.4.14 |
+-----------------------------+--------+-------------------+ +-----------------------------+--------+-------------------+
Table 5 Table 6
13.1.1. General Errors 13.1.1. General Errors
This section deals with errors that are applicable to a broad set of This section deals with errors that are applicable to a broad set of
different purposes. different purposes.
13.1.1.1. NFS4ERR_BADXDR (Error Code 10036) 13.1.1.1. NFS4ERR_BADXDR (Error Code 10036)
The arguments for this operation do not match those specified in the The arguments for this operation do not match those specified in the
XDR definition. This includes situations in which the request ends XDR definition. This includes situations in which the request ends
skipping to change at page 180, line 14 skipping to change at page 182, line 9
13.1.5.2. NFS4ERR_BAD_STATEID (Error Code 10025) 13.1.5.2. NFS4ERR_BAD_STATEID (Error Code 10025)
A stateid generated by the current server instance was used which A stateid generated by the current server instance was used which
either: either:
o Does not designate any locking state (either current or o Does not designate any locking state (either current or
superseded) for a current (state-owner, file) pair. superseded) for a current (state-owner, file) pair.
o Designates locking state that was freed after lease expiration but o Designates locking state that was freed after lease expiration but
without any lease cancelation, as may happen in the handling of without any lease cancellation, as may happen in the handling of
"courtesy locks". "courtesy locks".
13.1.5.3. NFS4ERR_EXPIRED (Error Code 10011) 13.1.5.3. NFS4ERR_EXPIRED (Error Code 10011)
A stateid or clientid designates locking state of any type that has A stateid or clientid designates locking state of any type that has
been revoked or released due to cancellation of the client's lease, been revoked or released due to cancellation of the client's lease,
either immediately upon lease expiration, or following a later either immediately upon lease expiration, or following a later
request for a conflicting lock. request for a conflicting lock.
13.1.5.4. NFS4ERR_LEASE_MOVED (Error Code 10031) 13.1.5.4. NFS4ERR_LEASE_MOVED (Error Code 10031)
skipping to change at page 183, line 14 skipping to change at page 185, line 8
13.1.8.7. NFS4ERR_LOCK_NOTSUPP (Error Code 10043) 13.1.8.7. NFS4ERR_LOCK_NOTSUPP (Error Code 10043)
A locking request was attempted which would require the upgrade or A locking request was attempted which would require the upgrade or
downgrade of a lock range already held by the owner when the server downgrade of a lock range already held by the owner when the server
does not support atomic upgrade or downgrade of locks. does not support atomic upgrade or downgrade of locks.
13.1.8.8. NFS4ERR_LOCK_RANGE (Error Code 10028) 13.1.8.8. NFS4ERR_LOCK_RANGE (Error Code 10028)
A lock request is operating on a range that overlaps in part a A lock request is operating on a range that overlaps in part a
currently held lock for the current lock owner and does not precisely currently held lock for the current lock-owner and does not precisely
match a single such lock where the server does not support this type match a single such lock where the server does not support this type
of request, and thus does not implement POSIX locking semantics of request, and thus does not implement POSIX locking semantics
[fcntl]. See Section 15.12.5, Section 15.13.5, and Section 15.14.5 [fcntl]. See Section 15.12.5, Section 15.13.5, and Section 15.14.5
for a discussion of how this applies to LOCK, LOCKT, and LOCKU for a discussion of how this applies to LOCK, LOCKT, and LOCKU
respectively. respectively.
13.1.8.9. NFS4ERR_OPENMODE (Error Code 10038) 13.1.8.9. NFS4ERR_OPENMODE (Error Code 10038)
The client attempted a READ, WRITE, LOCK or other operation not The client attempted a READ, WRITE, LOCK or other operation not
sanctioned by the stateid passed (e.g., writing to a file opened only sanctioned by the stateid passed (e.g., writing to a file opened only
for read). for read).
13.1.8.10. NFS4ERR_SHARE_DENIED (Error Code 10015)
An attempt to OPEN a file with a share reservation has failed because
of a share conflict.
13.1.9. Reclaim Errors 13.1.9. Reclaim Errors
These errors relate to the process of reclaiming locks after a server These errors relate to the process of reclaiming locks after a server
restart. restart.
13.1.9.1. NFS4ERR_GRACE (Error Code 10013) 13.1.9.1. NFS4ERR_GRACE (Error Code 10013)
The server is in its recovery or grace period which should at least The server is in its recovery or grace period which should at least
match the lease period of the server. A locking request other than a match the lease period of the server. A locking request other than a
reclaim could not be granted during that period. reclaim could not be granted during that period.
skipping to change at page 184, line 21 skipping to change at page 186, line 20
held by another client. Unlike NFS4ERR_RECLAIM_BAD, this can only held by another client. Unlike NFS4ERR_RECLAIM_BAD, this can only
occur if one of the clients misbehaved. occur if one of the clients misbehaved.
13.1.10. Client Management Errors 13.1.10. Client Management Errors
This sections deals with errors associated with requests used to This sections deals with errors associated with requests used to
create and manage client IDs. create and manage client IDs.
13.1.10.1. NFS4ERR_CLID_INUSE (Error Code 10017) 13.1.10.1. NFS4ERR_CLID_INUSE (Error Code 10017)
The SETCLIENTID operation has found that a client id is already in The SETCLIENTID operation has found that a clientid is already in use
use by another client. by another client.
13.1.10.2. NFS4ERR_STALE_CLIENTID (Error Code 10022) 13.1.10.2. NFS4ERR_STALE_CLIENTID (Error Code 10022)
A client ID not recognized by the server was used in a locking or A client ID not recognized by the server was used in a locking or
SETCLIENTID_CONFIRM request. SETCLIENTID_CONFIRM request.
13.1.11. Attribute Handling Errors 13.1.11. Attribute Handling Errors
This section deals with errors specific to attribute handling within This section deals with errors specific to attribute handling within
NFSv4. NFSv4.
skipping to change at page 185, line 11 skipping to change at page 187, line 11
This error is returned by the VERIFY operation to signify that the This error is returned by the VERIFY operation to signify that the
attributes compared were not the same as those provided in the attributes compared were not the same as those provided in the
client's request. client's request.
13.1.11.4. NFS4ERR_SAME (Error Code 10009) 13.1.11.4. NFS4ERR_SAME (Error Code 10009)
This error is returned by the NVERIFY operation to signify that the This error is returned by the NVERIFY operation to signify that the
attributes compared were the same as those provided in the client's attributes compared were the same as those provided in the client's
request. request.
13.1.12. Miscellaneous Errors
13.1.12.1. NFS4ERR_CB_PATH_DOWN (Error Code 10048)
There is a problem contacting the client via the callback path.
13.2. Operations and their valid errors 13.2. Operations and their valid errors
This section contains a table which gives the valid error returns for This section contains a table which gives the valid error returns for
each protocol operation. The error code NFS4_OK (indicating no each protocol operation. The error code NFS4_OK (indicating no
error) is not listed but should be understood to be returnable by all error) is not listed but should be understood to be returnable by all
operations except ILLEGAL. operations except ILLEGAL.
Valid error returns for each protocol operation Valid error returns for each protocol operation
+---------------------+---------------------------------------------+ +---------------------+---------------------------------------------+
skipping to change at page 192, line 28 skipping to change at page 194, line 34
| | NFS4ERR_LOCKED, NFS4ERR_MOVED, | | | NFS4ERR_LOCKED, NFS4ERR_MOVED, |
| | NFS4ERR_NOFILEHANDLE, NFS4ERR_NOSPC, | | | NFS4ERR_NOFILEHANDLE, NFS4ERR_NOSPC, |
| | NFS4ERR_NXIO, NFS4ERR_OLD_STATEID, | | | NFS4ERR_NXIO, NFS4ERR_OLD_STATEID, |
| | NFS4ERR_OPENMODE, NFS4ERR_RESOURCE, | | | NFS4ERR_OPENMODE, NFS4ERR_RESOURCE, |
| | NFS4ERR_ROFS, NFS4ERR_SERVERFAULT, | | | NFS4ERR_ROFS, NFS4ERR_SERVERFAULT, |
| | NFS4ERR_STALE, NFS4ERR_STALE_STATEID, | | | NFS4ERR_STALE, NFS4ERR_STALE_STATEID, |
| | NFS4ERR_SYMLINK | | | NFS4ERR_SYMLINK |
| | | | | |
+---------------------+---------------------------------------------+ +---------------------+---------------------------------------------+
Table 6 Table 7
13.3. Callback operations and their valid errors 13.3. Callback operations and their valid errors
This section contains a table which gives the valid error returns for This section contains a table which gives the valid error returns for
each callback operation. The error code NFS4_OK (indicating no each callback operation. The error code NFS4_OK (indicating no
error) is not listed but should be understood to be returnable by all error) is not listed but should be understood to be returnable by all
callback operations with the exception of CB_ILLEGAL. callback operations with the exception of CB_ILLEGAL.
Valid error returns for each protocol callback operation Valid error returns for each protocol callback operation
skipping to change at page 193, line 22 skipping to change at page 195, line 22
| | NFS4ERR_INVAL, NFS4ERR_SERVERFAULT | | | NFS4ERR_INVAL, NFS4ERR_SERVERFAULT |
| | | | | |
| CB_ILLEGAL | NFS4ERR_BADXDR, NFS4ERR_OP_ILLEGAL | | CB_ILLEGAL | NFS4ERR_BADXDR, NFS4ERR_OP_ILLEGAL |
| | | | | |
| CB_RECALL | NFS4ERR_BADHANDLE, NFS4ERR_BADXDR, | | CB_RECALL | NFS4ERR_BADHANDLE, NFS4ERR_BADXDR, |
| | NFS4ERR_BAD_STATEID, NFS4ERR_DELAY, | | | NFS4ERR_BAD_STATEID, NFS4ERR_DELAY, |
| | NFS4ERR_SERVERFAULT | | | NFS4ERR_SERVERFAULT |
| | | | | |
+-------------+-----------------------------------------------------+ +-------------+-----------------------------------------------------+
Table 7 Table 8
13.4. Errors and the operations that use them 13.4. Errors and the operations that use them
Errors and the operations that use them
+--------------------------+----------------------------------------+ +--------------------------+----------------------------------------+
| Error | Operations | | Error | Operations |
+--------------------------+----------------------------------------+ +--------------------------+----------------------------------------+
| NFS4ERR_ACCESS | ACCESS, COMMIT, CREATE, GETATTR, LINK, | | NFS4ERR_ACCESS | ACCESS, COMMIT, CREATE, GETATTR, LINK, |
| | LOCK, LOCKT, LOCKU, LOOKUP, LOOKUPP, | | | LOCK, LOCKT, LOCKU, LOOKUP, LOOKUPP, |
| | NVERIFY, OPEN, OPENATTR, READ, | | | NVERIFY, OPEN, OPENATTR, READ, |
| | READDIR, READLINK, REMOVE, RENAME, | | | READDIR, READLINK, REMOVE, RENAME, |
| | RENEW, SECINFO, SETATTR, VERIFY, WRITE | | | RENEW, SECINFO, SETATTR, VERIFY, WRITE |
| | | | | |
| NFS4ERR_ADMIN_REVOKED | CLOSE, DELEGRETURN, LOCK, LOCKU, OPEN, | | NFS4ERR_ADMIN_REVOKED | CLOSE, DELEGRETURN, LOCK, LOCKU, OPEN, |
skipping to change at page 198, line 40 skipping to change at page 200, line 42
| | | | | |
| NFS4ERR_TOOSMALL | READDIR | | NFS4ERR_TOOSMALL | READDIR |
| | | | | |
| NFS4ERR_WRONGSEC | LINK, LOOKUP, LOOKUPP, OPEN, PUTFH, | | NFS4ERR_WRONGSEC | LINK, LOOKUP, LOOKUPP, OPEN, PUTFH, |
| | PUTPUBFH, PUTROOTFH, RENAME, RESTOREFH | | | PUTPUBFH, PUTROOTFH, RENAME, RESTOREFH |
| | | | | |
| NFS4ERR_XDEV | LINK, RENAME | | NFS4ERR_XDEV | LINK, RENAME |
| | | | | |
+--------------------------+----------------------------------------+ +--------------------------+----------------------------------------+
Table 8 Table 9
14. NFSv4 Requests 14. NFSv4 Requests
For the NFSv4 RPC program, there are two traditional RPC procedures: For the NFSv4 RPC program, there are two traditional RPC procedures:
NULL and COMPOUND. All other functionality is defined as a set of NULL and COMPOUND. All other functionality is defined as a set of
operations and these operations are defined in normal XDR/RPC syntax operations and these operations are defined in normal XDR/RPC syntax
and semantics. However, these operations are encapsulated within the and semantics. However, these operations are encapsulated within the
COMPOUND procedure. This requires that the client combine one or COMPOUND procedure. This requires that the client combine one or
more of the NFSv4 operations into a single request. more of the NFSv4 operations into a single request.
skipping to change at page 203, line 38 skipping to change at page 205, line 38
does not support, the server MUST return an error of does not support, the server MUST return an error of
NFS4ERR_MINOR_VERS_MISMATCH and a zero length resultdata array. NFS4ERR_MINOR_VERS_MISMATCH and a zero length resultdata array.
Contained within the COMPOUND results is a "status" field. If the Contained within the COMPOUND results is a "status" field. If the
results array length is non-zero, this status must be equivalent to results array length is non-zero, this status must be equivalent to
the status of the last operation that was executed within the the status of the last operation that was executed within the
COMPOUND procedure. Therefore, if an operation incurred an error COMPOUND procedure. Therefore, if an operation incurred an error
then the "status" value will be the same error value as is being then the "status" value will be the same error value as is being
returned for the operation that failed. returned for the operation that failed.
Note that operations, 0 (zero) and 1 (one) are not defined for the Note that operations, 0 (zero), 1 (one), and 2 (two) are not defined
COMPOUND procedure. Operation 2 is not defined but reserved for for the COMPOUND procedure. It is possible that the server receives
future definition and use with minor versioning. If the server a request that contains an operation that is less than the first
receives a operation array that contains operation 2 and the legal operation (OP_ACCESS) or greater than the last legal operation
minorversion field has a value of 0 (zero), an error of (OP_RELEASE_LOCKOWNER). In this case, the server's response will
NFS4ERR_OP_ILLEGAL, as described in the next paragraph, is returned encode the opcode OP_ILLEGAL rather than the illegal opcode of the
to the client. If an operation array contains an operation 2 and the request. The status field in the ILLEGAL return results will set to
minorversion field is non-zero and the server does not support the NFS4ERR_OP_ILLEGAL. The COMPOUND procedure's return results will
minor version, the server returns an error of also be NFS4ERR_OP_ILLEGAL.
NFS4ERR_MINOR_VERS_MISMATCH. Therefore, the
NFS4ERR_MINOR_VERS_MISMATCH error takes precedence over all other
errors.
It is possible that the server receives a request that contains an
operation that is less than the first legal operation (OP_ACCESS) or
greater than the last legal operation (OP_RELEASE_LOCKOWNER). In
this case, the server's response will encode the opcode OP_ILLEGAL
rather than the illegal opcode of the request. The status field in
the ILLEGAL return results will set to NFS4ERR_OP_ILLEGAL. The
COMPOUND procedure's return results will also be NFS4ERR_OP_ILLEGAL.
The definition of the "tag" in the request is left to the The definition of the "tag" in the request is left to the
implementer. It may be used to summarize the content of the compound implementer. It may be used to summarize the content of the compound
request for the benefit of packet sniffers and engineers debugging request for the benefit of packet sniffers and engineers debugging
implementations. However, the value of "tag" in the response SHOULD implementations. However, the value of "tag" in the response SHOULD
be the same value as provided in the request. This applies to the be the same value as provided in the request. This applies to the
tag field of the CB_COMPOUND procedure as well. tag field of the CB_COMPOUND procedure as well.
15.2.4.1. Current Filehandle 15.2.4.1. Current Filehandle
skipping to change at page 205, line 26 skipping to change at page 207, line 15
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.
The client SHOULD NOT construct a COMPOUND which mixes operations for A single compound should not contain multiple operations that have
different client IDs. different values for the clientid field used in OPEN, LOCK, RENEW.
This can cause confusion in cases in which operations that do not
contain clientids have potential interactions with operations that
do. When only a single clientid has been used, it is clear what
client is being referenced. For a particular example involving the
interaction of OPEN and GETATTR, see Section 15.18.6.
15.3. Operation 3: ACCESS - Check Access Rights 15.3. Operation 3: ACCESS - Check Access Rights
15.3.1. SYNOPSIS 15.3.1. SYNOPSIS
(cfh), accessreq -> supported, accessrights (cfh), accessreq -> supported, accessrights
15.3.2. ARGUMENT 15.3.2. ARGUMENT
const ACCESS4_READ = 0x00000001; const ACCESS4_READ = 0x00000001;
skipping to change at page 208, line 7 skipping to change at page 210, line 4
determine access rights. It is the effective user and group determine access rights. It is the effective user and group
credentials that are used in subsequent read and write operations. credentials that are used in subsequent read and write operations.
Many implementations do not directly support the ACCESS4_DELETE Many implementations do not directly support the ACCESS4_DELETE
permission. Operating systems like UNIX will ignore the permission. Operating systems like UNIX will ignore the
ACCESS4_DELETE bit if set on an access request on a non-directory ACCESS4_DELETE bit if set on an access request on a non-directory
object. In these systems, delete permission on a file is determined object. In these systems, delete permission on a file is determined
by the access permissions on the directory in which the file resides, by the access permissions on the directory in which the file resides,
instead of being determined by the permissions of the file itself. instead of being determined by the permissions of the file itself.
Therefore, the mask returned enumerating which access rights can be Therefore, the mask returned enumerating which access rights can be
determined will have the ACCESS4_DELETE value set to 0. This supported will have the ACCESS4_DELETE value set to 0. This
indicates to the client that the server was unable to check that indicates to the client that the server was unable to check that
particular access right. The ACCESS4_DELETE bit in the access mask particular access right. The ACCESS4_DELETE bit in the access mask
returned will then be ignored by the client. returned will then be ignored by the client.
15.4. Operation 4: CLOSE - Close File 15.4. Operation 4: CLOSE - Close File
15.4.1. SYNOPSIS 15.4.1. SYNOPSIS
(cfh), seqid, open_stateid -> open_stateid (cfh), seqid, open_stateid -> open_stateid
skipping to change at page 220, line 15 skipping to change at page 222, line 15
15.11.5. IMPLEMENTATION 15.11.5. IMPLEMENTATION
Changes to any property of the "hard" linked files are reflected in Changes to any property of the "hard" linked files are reflected in
all of the linked files. When a link is made to a file, the all of the linked files. When a link is made to a file, the
attributes for the file should have a value for numlinks that is one attributes for the file should have a value for numlinks that is one
greater than the value before the LINK operation. greater than the value before the LINK operation.
The statement "file and the target directory must reside within the The statement "file and the target directory must reside within the
same file system on the server" means that the fsid fields in the same file system on the server" means that the fsid fields in the
attributes for the objects are the same. If they reside on different attributes for the objects are the same. If they reside on different
file systems, the error, NFS4ERR_XDEV, is returned. On some servers, file systems, the error NFS4ERR_XDEV is returned. This error may be
the filenames, "." and "..", are illegal as newname. returned by some servers when there is an internal partitioning of a
file system that the LINK operation would violate.
On some servers, "." and ".." are illegal values for newname and the
error NFS4ERR_BADNAME will be returned if they are specified.
When the current filehandle designates a named attribute directory
and the object to be linked (the saved filehandle) is not a named
attribute for the same object, the error NFS4ERR_XDEV MUST be
returned. When the saved filehandle designates a named attribute and
the current filehandle is not the appropriate named attribute
directory, the error NFS4ERR_XDEV MUST also be returned.
When the current filehandle designates a named attribute directory
and the object to be linked (the saved filehandle) is a named
attribute within that directory, the server MAY return the error
NFS4ERR_NOTSUPP.
In the case that newname is already linked to the file represented by In the case that newname is already linked to the file represented by
the saved filehandle, the server will return NFS4ERR_EXIST. the saved filehandle, the server will return NFS4ERR_EXIST.
Note that symbolic links are created with the CREATE operation. Note that symbolic links are created with the CREATE operation.
15.12. Operation 12: LOCK - Create Lock 15.12. Operation 12: LOCK - Create Lock
15.12.1. SYNOPSIS 15.12.1. SYNOPSIS
skipping to change at page 230, line 12 skipping to change at page 232, line 12
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 mount points. 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.
If the current filehandle is a named attribute directory that is
associated with a file system object via OPENATTR (i.e., not a sub-
directory of a named attribute directory), LOOKUPP SHOULD return the
filehandle of the associated file system object.
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 -> -
15.17.2. ARGUMENT 15.17.2. ARGUMENT
struct NVERIFY4args { struct NVERIFY4args {
/* CURRENT_FH: object */ /* CURRENT_FH: object */
skipping to change at page 231, line 10 skipping to change at page 233, line 12
object to which the attributes belong has changed then the following object to which the attributes belong has changed then the following
operations may obtain new data associated with that object. For operations may obtain new data associated with that object. For
instance, to check if a file has been changed and obtain new data if instance, to check if a file has been changed and obtain new data if
it has: it has:
PUTFH (public) PUTFH (public)
LOOKUP "foobar" LOOKUP "foobar"
NVERIFY attrbits attrs NVERIFY attrbits attrs
READ 0 32767 READ 0 32767
In the case that a recommended attribute is specified in the NVERIFY In the case that a RECOMMENDED attribute is specified in the NVERIFY
operation and the server does not support that attribute for the file operation and the server does not support that attribute for the file
system object, the error NFS4ERR_ATTRNOTSUPP is returned to the system object, the error NFS4ERR_ATTRNOTSUPP is returned to the
client. client.
When the attribute rdattr_error or any write-only attribute (e.g., When the attribute rdattr_error or any write-only attribute (e.g.,
time_modify_set) is specified, the error NFS4ERR_INVAL is returned to time_modify_set) is specified, the error NFS4ERR_INVAL is returned to
the client. the client.
15.18. Operation 18: OPEN - Open a Regular File 15.18. Operation 18: OPEN - Open a Regular File
skipping to change at page 235, line 25 skipping to change at page 237, line 25
}; };
union OPEN4res switch (nfsstat4 status) { union OPEN4res switch (nfsstat4 status) {
case NFS4_OK: case NFS4_OK:
/* CURRENT_FH: opened file */ /* CURRENT_FH: opened file */
OPEN4resok resok4; OPEN4resok resok4;
default: default:
void; void;
}; };
15.18.4. Warning to Client Implementors 15.18.4. Warning to Client Implementers
OPEN resembles LOOKUP in that it generates a filehandle for the OPEN resembles LOOKUP in that it generates a filehandle for the
client to use. Unlike LOOKUP though, OPEN creates server state on client to use. Unlike LOOKUP though, OPEN creates server state on
the filehandle. In normal circumstances, the client can only release the filehandle. In normal circumstances, the client can only release
this state with a CLOSE operation. CLOSE uses the current filehandle this state with a CLOSE operation. CLOSE uses the current filehandle
to determine which file to close. Therefore, the client MUST follow to determine which file to close. Therefore, the client MUST follow
every OPEN operation with a GETFH operation in the same COMPOUND every OPEN operation with a GETFH operation in the same COMPOUND
procedure. This will supply the client with the filehandle such that procedure. This will supply the client with the filehandle such that
CLOSE can be used appropriately. CLOSE can be used appropriately.
skipping to change at page 238, line 43 skipping to change at page 240, line 43
When an OPEN is done and the specified open-owner already has the When an OPEN is done and the specified open-owner already has the
resulting filehandle open, the result is to "OR" together the new resulting filehandle open, the result is to "OR" together the new
share and deny status together with the existing status. In this share and deny status together with the existing status. In this
case, only a single CLOSE need be done, even though multiple OPENs case, only a single CLOSE need be done, even though multiple OPENs
were completed. When such an OPEN is done, checking of share were completed. When such an OPEN is done, checking of share
reservations for the new OPEN proceeds normally, with no exception reservations for the new OPEN proceeds normally, with no exception
for the existing OPEN held by the same owner. In this case, the for the existing OPEN held by the same owner. In this case, the
stateid returned as an "other" field that matches that of the stateid returned as an "other" field that matches that of the
previous open while the "seqid" field is incremented to reflect the previous open while the "seqid" field is incremented to reflect the
change status due to the new open. change status due to the new open (Section 9.1.4).
If the underlying file system at the server is only accessible in a If the underlying file system at the server is only accessible in a
read-only mode and the OPEN request has specified ACCESS_WRITE or read-only mode and the OPEN request has specified
ACCESS_BOTH, the server will return NFS4ERR_ROFS to indicate a read- OPEN4_SHARE_ACCESSS_WRITE or OPEN4_SHARE_ACCESS_BOTH, the server will
only file system. return NFS4ERR_ROFS to indicate a read-only file system.
As with the CREATE operation, the server MUST derive the owner, owner As with the CREATE operation, the server MUST derive the owner, owner
ACE, group, or group ACE if any of the four attributes are required ACE, group, or group ACE if any of the four attributes are required
and supported by the server's file system. For an OPEN with the and supported by the server's file system. For an OPEN with the
EXCLUSIVE4 createmode, the server has no choice, since such OPEN EXCLUSIVE4 createmode, the server has no choice, since such OPEN
calls do not include the createattrs field. Conversely, if calls do not include the createattrs field. Conversely, if
createattrs is specified, and includes owner or group (or createattrs is specified, and includes owner or group (or
corresponding ACEs) that the principal in the RPC call's credentials corresponding ACEs) that the principal in the RPC call's credentials
does not have authorization to create files for, then the server may does not have authorization to create files for, then the server may
return NFS4ERR_PERM. return NFS4ERR_PERM.
skipping to change at page 240, line 30 skipping to change at page 242, line 30
semantics. In particular, if a reply is lost and the server does not semantics. In particular, if a reply is lost and the server does not
detect the retransmission of the request, the operation can fail with detect the retransmission of the request, the operation can fail with
NFS4ERR_EXIST, even though the create was performed successfully. NFS4ERR_EXIST, even though the create was performed successfully.
The client would use this behavior in the case that the application The client would use this behavior in the case that the application
has not requested an exclusive create but has asked to have the file has not requested an exclusive create but has asked to have the file
truncated when the file is opened. In the case of the client timing truncated when the file is opened. In the case of the client timing
out and retransmitting the create request, the client can use out and retransmitting the create request, the client can use
GUARDED4 to prevent against a sequence like: create, write, create GUARDED4 to prevent against a sequence like: create, write, create
(retransmitted) from occurring. (retransmitted) from occurring.
For SHARE reservations, the client must specify a value for For SHARE reservations (see Section 9.9), the client must specify a
share_access that is one of READ, WRITE, or BOTH. For share_deny, value for share_access that is one of OPEN4_SHARE_ACCESS_READ,
the client must specify one of NONE, READ, WRITE, or BOTH. If the OPEN4_SHARE_ACCESS_WRITE, or OPEN4_SHARE_ACCESS_BOTH. For
client fails to do this, the server must return NFS4ERR_INVAL. share_deny, the client must specify one of OPEN4_SHARE_DENY_NONE,
OPEN4_SHARE_DENY_READ, OPEN4_SHARE_DENY_WRITE, or
OPEN4_SHARE_DENY_BOTH. If the client fails to do this, the server
must return NFS4ERR_INVAL.
Based on the share_access value (READ, WRITE, or BOTH) the client Based on the share_access value (OPEN4_SHARE_ACCESS_READ,
OPEN4_SHARE_ACCESS_WRITE, or OPEN4_SHARE_ACCESS_BOTH) the client
should check that the requester has the proper access rights to should check that the requester has the proper access rights to
perform the specified operation. This would generally be the results perform the specified operation. This would generally be the results
of applying the ACL access rules to the file for the current of applying the ACL access rules to the file for the current
requester. However, just as with the ACCESS operation, the client requester. However, just as with the ACCESS operation, the client
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 resolves to something other than a If the component provided to OPEN resolves to something other than a
regular file, an error will be returned to the client. If it is a regular file (or a named attribute), an error will be returned to the
directory, NFS4ERR_ISDIR is returned; otherwise, NFS4ERR_SYMLINK is client. If it is a directory, NFS4ERR_ISDIR is returned; otherwise,
returned. Note that NFS4ERR_SYMLINK is returned for both symlinks NFS4ERR_SYMLINK is returned. Note that NFS4ERR_SYMLINK is returned
and for special files of other types; NFS4ERR_INVAL would be for both symlinks and for special files of other types; NFS4ERR_INVAL
inappropriate, since the arguments provided by the client were would be inappropriate, since the arguments provided by the client
correct, and the client cannot necessarily know at the time it sent were correct, and the client cannot necessarily know at the time it
the OPEN that the component would resolve to a non-regular file. sent the OPEN that the component would resolve to a non-regular file.
If the current filehandle is not a directory, the error If the current filehandle is not a directory, the error
NFS4ERR_NOTDIR will be returned. NFS4ERR_NOTDIR will be returned.
If a COMPOUND contains an OPEN which establishes a If a COMPOUND contains an OPEN which establishes an
OPEN_DELEGATE_WRITE delegation, then a subsequent GETATTR inside that OPEN_DELEGATE_WRITE delegation, then normally subsequent GETATTRs
COMPOUND SHOULD NOT result in a CB_GETATTR to the client. The server result in a CB_GETATTR being sent to the client holding the
SHOULD understand the GETATTR to be for the same client ID and avoid delegation. However, in the case in which the OPEN and GETATTR are
querying the client, which will not be able to respond. This part of the same COMPOUND, the server SHOULD understand that the
sequence of OPEN, GETATTR SHOULD be understood as an atomic retrieval operations are for the same client ID and avoid querying the client,
of the initial size and change attribute. Further, the client SHOULD which will not be able to respond. This sequence of OPEN, GETATTR
NOT construct a COMPOUND which mixes operations for different client SHOULD be understood as retrieving of the size and change attributes
IDs. at the time of OPEN, Further, as explained in Section 15.2.5, the
client should not construct a COMPOUND which mixes operations for
different client IDs.
15.19. Operation 19: OPENATTR - Open Named Attribute Directory 15.19. Operation 19: OPENATTR - Open Named Attribute Directory
15.19.1. SYNOPSIS 15.19.1. SYNOPSIS
(cfh) createdir -> (cfh) (cfh) createdir -> (cfh)
15.19.2. ARGUMENT 15.19.2. ARGUMENT
struct OPENATTR4args { struct OPENATTR4args {
skipping to change at page 243, line 22 skipping to change at page 245, line 22
void; void;
}; };
15.20.4. DESCRIPTION 15.20.4. DESCRIPTION
This operation is used to confirm the sequence id usage for the first This operation is used to confirm the sequence id usage for the first
time that a open-owner is used by a client. The stateid returned time that a open-owner is used by a client. The stateid returned
from the OPEN operation is used as the argument for this operation from the OPEN operation is used as the argument for this operation
along with the next sequence id for the open-owner. The sequence id along with the next sequence id for the open-owner. The sequence id
passed to the OPEN_CONFIRM must be 1 (one) greater than the seqid passed to the OPEN_CONFIRM must be 1 (one) greater than the seqid
passed to the OPEN operation. If the server receives an unexpected passed to the OPEN operation (Section 9.1.4). If the server receives
sequence id with respect to the original open, then the server an unexpected sequence id with respect to the original open, then the
assumes that the client will not confirm the original OPEN and all server assumes that the client will not confirm the original OPEN and
state associated with the original OPEN is released by the server. all state associated with the original OPEN is released by the
server.
On success, the current filehandle retains its value. On success, the current filehandle retains its value.
15.20.5. IMPLEMENTATION 15.20.5. IMPLEMENTATION
A given client might generate many open_owner4 data structures for a A given client might generate many open_owner4 data structures for a
given client ID. The client will periodically either dispose of its given client ID. The client will periodically either dispose of its
open_owner4s or stop using them for indefinite periods of time. The open_owner4s or stop using them for indefinite periods of time. The
latter situation is why the NFSv4 protocol does not have an explicit latter situation is why the NFSv4 protocol does not have an explicit
operation to exit an open_owner4: such an operation is of no use in operation to exit an open_owner4: such an operation is of no use in
skipping to change at page 243, line 50 skipping to change at page 246, line 6
an implementation choice. The time period should certainly be no an implementation choice. The time period should certainly be no
less than the lease time plus any grace period the server wishes to less than the lease time plus any grace period the server wishes to
implement beyond a lease time. The OPEN_CONFIRM operation allows the implement beyond a lease time. The OPEN_CONFIRM operation allows the
server to safely dispose of unused open_owner4 data structures. server to safely dispose of unused open_owner4 data structures.
In the case that a client issues an OPEN operation and the server no In the case that a client issues an OPEN operation and the server no
longer has a record of the open_owner4, the server needs to ensure longer has a record of the open_owner4, the server needs to ensure
that this is a new OPEN and not a replay or retransmission. that this is a new OPEN and not a replay or retransmission.
Servers MUST NOT require confirmation on OPENs that grant delegations Servers MUST NOT require confirmation on OPENs that grant delegations
or are doing reclaim operations. See Section 9.1.10 for details. or are doing reclaim operations. See Section 9.1.11 for details.
The server can easily avoid this by noting whether it has disposed of The server can easily avoid this by noting whether it has disposed of
one open_owner4 for the given client ID. If the server does not one open_owner4 for the given client ID. If the server does not
support delegation, it might simply maintain a single bit that notes support delegation, it might simply maintain a single bit that notes
whether any open_owner4 (for any client) has been disposed of. whether any open_owner4 (for any client) has been disposed of.
The server must hold unconfirmed OPEN state until one of three events The server must hold unconfirmed OPEN state until one of three events
occur. First, the client sends an OPEN_CONFIRM request with the occur. First, the client sends an OPEN_CONFIRM request with the
appropriate sequence id and stateid within the lease period. In this appropriate sequence id and stateid within the lease period. In this
case, the OPEN state on the server goes to confirmed, and the case, the OPEN state on the server goes to confirmed, and the
open_owner4 on the server is fully established. open_owner4 on the server is fully established.
skipping to change at page 247, line 19 skipping to change at page 249, line 19
nfsstat4 status; nfsstat4 status;
}; };
15.23.4. DESCRIPTION 15.23.4. DESCRIPTION
Replaces the current filehandle with the filehandle that represents Replaces the current filehandle with the filehandle that represents
the public filehandle of the server's name space. This filehandle the public filehandle of the server's name space. This filehandle
may be different from the "root" filehandle which may be associated may be different from the "root" filehandle which may be associated
with some other directory on the server. with some other directory on the server.
The public filehandle represents the concepts embodied in [RFC2054], The public filehandle concept was introduced in [RFC2054], [RFC2055],
[RFC2055], [RFC2224]. The intent for NFSv4 is that the public [RFC2224]. The intent for NFSv4 is that the public filehandle
filehandle (represented by the PUTPUBFH operation) be used as a (represented by the PUTPUBFH operation) be used as a method of
method of providing WebNFS server compatibility with NFSv2 and NFSv3. providing compatibility with the WebNFS server of NFSv2 and NFSv3.
The public filehandle and the root filehandle (represented by the The public filehandle and the root filehandle (represented by the
PUTROOTFH operation) should be equivalent. If the public and root PUTROOTFH operation) should be equivalent. If the public and root
filehandles are not equivalent, then the public filehandle MUST be a filehandles are not equivalent, then the public filehandle MUST be a
descendant of the root filehandle. descendant of the root filehandle.
15.23.5. IMPLEMENTATION 15.23.5. IMPLEMENTATION
Used as the first operator in an NFS request to set the context for Used as the first operator in an NFS request to set the context for
following operations. following operations.
skipping to change at page 248, line 8 skipping to change at page 250, line 8
Note that there are warnings mentioned in [RFC2224] with respect to Note that there are warnings mentioned in [RFC2224] with respect to
the use of absolute evaluation and the restrictions the server may the use of absolute evaluation and the restrictions the server may
place on that evaluation with respect to how much of its namespace place on that evaluation with respect to how much of its namespace
has been made available. These same warnings apply to NFSv4. It is has been made available. These same warnings apply to NFSv4. It is
likely, therefore that because of server implementation details, an likely, therefore that because of server implementation details, an
NFSv3 absolute public filehandle lookup may behave differently than NFSv3 absolute public filehandle lookup may behave differently than
an NFSv4 absolute resolution. an NFSv4 absolute resolution.
There is a form of security negotiation as described in [RFC2755] There is a form of security negotiation as described in [RFC2755]
that uses the public filehandle a method of employing Simple and that uses the public filehandle as a method of employing Simple and
Protected GSSAPI Negotiation Mechanism (SNEGO) [RFC4178]. This Protected GSSAPI Negotiation Mechanism (SNEGO) [RFC4178]. This
method is not available with NFSv4 as filehandles are not overloaded method is not available with NFSv4 as filehandles are not overloaded
with special meaning and therefore do not provide the same framework with special meaning and therefore do not provide the same framework
as NFSv2 and NFSv3. Clients should therefore use the security as NFSv2 and NFSv3. Clients should therefore use the security
negotiation mechanisms described in this RFC. negotiation mechanisms described in this RFC.
15.24. Operation 24: PUTROOTFH - Set Root Filehandle 15.24. Operation 24: PUTROOTFH - Set Root Filehandle
15.24.1. SYNOPSIS 15.24.1. SYNOPSIS
skipping to change at page 250, line 24 skipping to change at page 252, line 24
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 returned; 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 using the special anonymous stateid, 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 using the special
value of all bits 1, the server MAY allow READ operations to bypass READ bypass stateid, 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.
15.25.5. IMPLEMENTATION 15.25.5. IMPLEMENTATION
If the server returns a "short read" (i.e., fewer data than requested If the server returns a "short read" (i.e., fewer data than requested
and eof is set to FALSE), the client should send another READ to get and eof is set to FALSE), the client should send another READ to get
the remaining data. A server may return less data than requested the remaining data. A server may return less data than requested
under several circumstances. The file may have been truncated by under several circumstances. The file may have been truncated by
skipping to change at page 253, line 32 skipping to change at page 255, line 32
On successful return, the server's response will provide a list of On successful return, the server's response will provide a list of
directory entries. Each of these entries contains the name of the directory entries. Each of these entries contains the name of the
directory entry, a cookie value for that entry, and the associated directory entry, a cookie value for that entry, and the associated
attributes as requested. The "eof" flag has a value of TRUE if there attributes as requested. The "eof" flag has a value of TRUE if there
are no more entries in the directory. are no more entries in the directory.
The cookie value is only meaningful to the server and is used as a The cookie value is only meaningful to the server and is used as a
"bookmark" for the directory entry. As mentioned, this cookie is "bookmark" for the directory entry. As mentioned, this cookie is
used by the client for subsequent READDIR operations so that it may used by the client for subsequent READDIR operations so that it may
continue reading a directory. The cookie is similar in concept to a continue reading a directory. The cookie is similar in concept to a
READ offset but should not be interpreted as such by the client. READ offset but should not be interpreted as such by the client. The
Ideally, the cookie value should not change if the directory is server SHOULD try to accept cookie values issued with READDIR
modified since the client may be caching these values. responses even if the directory has been modified between the READDIR
calls but MAY return NFS4ERR_NOT_VALID if this is not possible as
might be the case if the server has rebooted in the interim.
In some cases, the server may encounter an error while obtaining the In some cases, the server may encounter an error while obtaining the
attributes for a directory entry. Instead of returning an error for attributes for a directory entry. Instead of returning an error for
the entire READDIR operation, the server can instead return the the entire READDIR operation, the server can instead return the
attribute 'fattr4_rdattr_error'. With this, the server is able to attribute 'fattr4_rdattr_error'. With this, the server is able to
communicate the failure to the client and not fail the entire communicate the failure to the client and not fail the entire
operation in the instance of what might be a transient failure. operation in the instance of what might be a transient failure.
Obviously, the client must request the fattr4_rdattr_error attribute Obviously, the client must request the fattr4_rdattr_error attribute
for this method to work properly. If the client does not request the for this method to work properly. If the client does not request the
attribute, the server has no choice but to return failure for the attribute, the server has no choice but to return failure for the
skipping to change at page 254, line 30 skipping to change at page 256, line 32
maxcount fields are provided to allow the client the ability to maxcount fields are provided to allow the client the ability to
provide guidelines to the server. If the client is aggressive about provide guidelines to the server. If the client is aggressive about
attribute collection during a READDIR, the server has an idea of how attribute collection during a READDIR, the server has an idea of how
to limit the encoded response. The dircount field provides a hint on to limit the encoded response. The dircount field provides a hint on
the number of entries based solely on the names of the directory the number of entries based solely on the names of the directory
entries. Since it is a hint, it may be possible that a dircount entries. Since it is a hint, it may be possible that a dircount
value is zero. In this case, the server is free to ignore the value is zero. In this case, the server is free to ignore the
dircount value and return directory information based on the dircount value and return directory information based on the
specified maxcount value. specified maxcount value.
As there is no way for the client to indicate that a cookie value
once received, will not be subsequently used, server implementations
should avoid schemes that allocate memory corresponding to a returned
cookie. Such allocation can be avoided if the server bases cookie
values on a value such as the offset within the directory where the
scan is to be resumed.
Cookies generated by such techniques should be designed to remain
valid despite modification of the associated directory. If a server
were to invalidate a cookie because of a directory modification,
READDIR's of large directories might never finish.
If a directory is deleted after the client has carried out one or
more READDIR operations on the directory, the cookies returned will
become invalid but the server does not need to be concerned as the
directory file handle used previously would have become stale and
would be reported as such on subsequent READDIR operations. The
server would not need to check the cookie verifier in this case.
However, certain re-organization operations on a directory (including
directory compaction) may invalidate READDDIR cookies previously
given out. When such a situation occurs, the server should modify
the cookie verifier so as to disallow use of cookies which would
otherwise no longer be valid.
The cookieverf may be used by the server to help manage cookie values The cookieverf may be used by the server to help manage cookie values
that may become stale. It should be a rare occurrence that a server that may become stale. It should be a rare occurrence that a server
is unable to continue properly reading a directory with the provided is unable to continue properly reading a directory with the provided
cookie/cookieverf pair. The server should make every effort to avoid cookie/cookieverf pair. The server should make every effort to avoid
this condition since the application at the client may not be able to this condition since the application at the client may not be able to
properly handle this type of failure. properly handle this type of failure.
The use of the cookieverf will also protect the client from using The use of the cookieverf will also protect the client from using
READDIR cookie values that may be stale. For example, if the file READDIR cookie values that may be stale. For example, if the file
system has been migrated, the server may or may not be able to use system has been migrated, the server may or may not be able to use
skipping to change at page 259, line 15 skipping to change at page 261, line 48
If oldname and newname both refer to the same file (they might be If oldname and newname both refer to the same file (they might be
hard links of each other), then RENAME should perform no action and hard links of each other), then RENAME should perform no action and
return success. return success.
For both directories involved in the RENAME, the server returns For both directories involved in the RENAME, the server returns
change_info4 information. With the atomic field of the change_info4 change_info4 information. With the atomic field of the change_info4
struct, the server will indicate if the before and after change struct, the server will indicate if the before and after change
attributes were obtained atomically with respect to the rename. attributes were obtained atomically with respect to the rename.
If the oldname refers to a named attribute and the saved and current If the oldname refers to a named attribute and the saved and current
filehandles refer to different file system objects, the server will filehandles refer to the named attribute directories of different
return NFS4ERR_XDEV just as if the saved and current filehandles file system objects, the server will return NFS4ERR_XDEV just as if
represented directories on different file systems. the saved and current filehandles represented directories on
different file systems.
If the oldname or newname is of zero length, NFS4ERR_INVAL will be If the oldname or newname is of zero length, NFS4ERR_INVAL will be
returned. The oldname and newname are also subject to the normal returned. The oldname and newname are also subject to the normal
UTF-8, character support, and name checks. See Section 12.7 for UTF-8, character support, and name checks. See Section 12.7 for
further discussion. further discussion.
15.29.5. IMPLEMENTATION 15.29.5. IMPLEMENTATION
The RENAME operation must be atomic to the client. The statement The RENAME operation must be atomic to the client. The statement
"source and target directories must reside on the same file system on "source and target directories must reside on the same file system on
skipping to change at page 260, line 47 skipping to change at page 263, line 35
also down. In the event that the server has conditions such that it also down. In the event that the server has conditions such that it
could return either NFS4ERR_CB_PATH_DOWN or NFS4ERR_LEASE_MOVED, could return either NFS4ERR_CB_PATH_DOWN or NFS4ERR_LEASE_MOVED,
NFS4ERR_LEASE_MOVED MUST be handled first. NFS4ERR_LEASE_MOVED MUST be handled first.
The client that issues RENEW MUST choose the principal, RPC security The client that issues RENEW MUST choose the principal, RPC security
flavor, and if applicable, GSS-API mechanism and service via one of flavor, and if applicable, GSS-API mechanism and service via one of
the following algorithms: the following algorithms:
o The client uses the same principal, RPC security flavor -- and if o The client uses the same principal, RPC security flavor -- and if
the flavor was RPCSEC_GSS -- the same mechanism and service that the flavor was RPCSEC_GSS -- the same mechanism and service that
was used when the client id was established via was used when the client ID was established via
SETCLIENTID_CONFIRM. SETCLIENTID_CONFIRM.
o The client uses any principal, RPC security flavor mechanism and o The client uses any principal, RPC security flavor mechanism and
service combination that currently has an OPEN file on the server. service combination that currently has an OPEN file on the server.
I.e., the same principal had a successful OPEN operation, the file I.e., the same principal had a successful OPEN operation, the file
is still open by that principal, and the flavor, mechanism, and is still open by that principal, and the flavor, mechanism, and
service of RENEW match that of the previous OPEN. service of RENEW match that of the previous OPEN.
The server MUST reject a RENEW that does not use one the The server MUST reject a RENEW that does not use one the
aforementioned algorithms, with the error NFS4ERR_ACCESS. aforementioned algorithms, with the error NFS4ERR_ACCESS.
skipping to change at page 265, line 48 skipping to change at page 268, line 39
return the NFS4ERR_WRONGSEC error in rdattr_error for the entry. return the NFS4ERR_WRONGSEC error in rdattr_error for the entry.
Note that a server MAY use the AUTH_NONE flavor to signify that the Note that a server MAY use the AUTH_NONE flavor to signify that the
client is allowed to attempt to use authentication flavors that are client is allowed to attempt to use authentication flavors that are
not explicitly listed in the SECINFO results. Instead of using a not explicitly listed in the SECINFO results. Instead of using a
listed flavor, the client might then, for instance opt to use an listed flavor, the client might then, for instance opt to use an
otherwise unlisted RPCSEC_GSS mechanism instead of AUTH_NONE. It may otherwise unlisted RPCSEC_GSS mechanism instead of AUTH_NONE. It may
wish to do so in order to meet an application requirement for data wish to do so in order to meet an application requirement for data
integrity or privacy. In choosing to use an unlisted flavor, the integrity or privacy. In choosing to use an unlisted flavor, the
client SHOULD always be prepared to handle a failure by falling back client SHOULD always be prepared to handle a failure by falling back
to using AUTH_NONE or another listed flavor. It MUST NOT assume that to using AUTH_NONE or another listed flavor. It cannot assume that
identity mapping is supported, and should be prepared for the fact identity mapping is supported, and should be prepared for the fact
that its identity is squashed. that its identity is squashed.
See Section 17 for a discussion on the recommendations for security See Section 17 for a discussion on the recommendations for security
flavor used by SECINFO. flavor used by SECINFO.
15.34. Operation 34: SETATTR - Set Attributes 15.34. Operation 34: SETATTR - Set Attributes
15.34.1. SYNOPSIS 15.34.1. SYNOPSIS
skipping to change at page 266, line 47 skipping to change at page 269, line 38
size attribute. Since setting the size attribute modifies the file's size attribute. Since setting the size attribute modifies the file's
data, it has the same locking requirements as a corresponding WRITE. data, it has the same locking requirements as a corresponding WRITE.
Any SETATTR that sets the size attribute is incompatible with a share Any SETATTR that sets the size attribute is incompatible with a share
reservation that specifies OPEN4_SHARE_DENY_WRITE. The area between reservation that specifies OPEN4_SHARE_DENY_WRITE. The area between
the old end-of-file and the new end-of-file is considered to be the old end-of-file and the new end-of-file is considered to be
modified just as would have been the case had the area in question modified just as would have been the case had the area in question
been specified as the target of WRITE, for the purpose of checking been specified as the target of WRITE, for the purpose of checking
conflicts with byte-range locks, for those cases in which a server is conflicts with byte-range locks, for those cases in which a server is
implementing mandatory byte-range locking behavior. A valid stateid implementing mandatory byte-range locking behavior. A valid stateid
SHOULD always be specified. When the file size attribute is not set, SHOULD always be specified. When the file size attribute is not set,
the special stateid consisting of all bits zero MAY be passed. the special anonymous stateid MAY be passed.
On either success or failure of the operation, the server will return On either success or failure of the operation, the server will return
the attrsset bitmask to represent what (if any) attributes were the attrsset bitmask to represent what (if any) attributes were
successfully set. The attrsset in the response is a subset of the successfully set. The attrsset in the response is a subset of the
bitmap4 that is part of the obj_attributes in the argument. bitmap4 that is part of the obj_attributes in the argument.
On success, the current filehandle retains its value. On success, the current filehandle retains its value.
15.34.5. IMPLEMENTATION 15.34.5. IMPLEMENTATION
skipping to change at page 270, line 36 skipping to change at page 273, line 36
the server is implementing the duplicate request cache (DRC). the server is implementing the duplicate request cache (DRC).
When the server gets a SETCLIENTID { v, x, k } request, it processes When the server gets a SETCLIENTID { v, x, k } request, it processes
it in the following manner. it in the following manner.
o It first looks up the request in the DRC. If there is a hit, it o It first looks up the request in the DRC. If there is a hit, it
returns the result cached in the DRC. The server does NOT remove returns the result cached in the DRC. The server does NOT remove
client state (locks, shares, delegations) nor does it modify any client state (locks, shares, delegations) nor does it modify any
recorded callback and callback_ident information for client { x }. recorded callback and callback_ident information for client { x }.
For any DRC miss, the server takes the client id string x, and For any DRC miss, the server takes the client ID string x, and
searches for client records for x that the server may have searches for client records for x that the server may have
recorded from previous SETCLIENTID calls. For any confirmed recorded from previous SETCLIENTID calls. For any confirmed
record with the same id string x, if the recorded principal does record with the same id string x, if the recorded principal does
not match that of SETCLIENTID call, then the server returns a not match that of SETCLIENTID call, then the server returns a
NFS4ERR_CLID_INUSE error. NFS4ERR_CLID_INUSE error.
For brevity of discussion, the remaining description of the For brevity of discussion, the remaining description of the
processing assumes that there was a DRC miss, and that where the processing assumes that there was a DRC miss, and that where the
server has previously recorded a confirmed record for client x, server has previously recorded a confirmed record for client x,
the aforementioned principal check has successfully passed. the aforementioned principal check has successfully passed.
skipping to change at page 276, line 43 skipping to change at page 279, line 43
PUTFH (directory filehandle) PUTFH (directory filehandle)
LOOKUP (file name) LOOKUP (file name)
VERIFY (filehandle == fh) VERIFY (filehandle == fh)
PUTFH (directory filehandle) PUTFH (directory filehandle)
REMOVE (file name) REMOVE (file name)
This sequence does not prevent a second client from removing and This sequence does not prevent a second client from removing and
creating a new file in the middle of this sequence but it does help creating a new file in the middle of this sequence but it does help
avoid the unintended result. avoid the unintended result.
In the case that a recommended attribute is specified in the VERIFY In the case that a RECOMMENDED attribute is specified in the VERIFY
operation and the server does not support that attribute for the file operation and the server does not support that attribute for the file
system object, the error NFS4ERR_ATTRNOTSUPP is returned to the system object, the error NFS4ERR_ATTRNOTSUPP is returned to the
client. client.
When the attribute rdattr_error or any write-only attribute (e.g., When the attribute rdattr_error or any write-only attribute (e.g.,
time_modify_set) is specified, the error NFS4ERR_INVAL is returned to time_modify_set) is specified, the error NFS4ERR_INVAL is returned to
the client. the client.
15.38. Operation 38: WRITE - Write to File 15.38. Operation 38: WRITE - Write to File
skipping to change at page 279, line 21 skipping to change at page 282, line 21
uncommitted data may be lost. uncommitted data may be lost.
If a client writes data to the server with the stable argument set to If a client writes data to the server with the stable argument set to
UNSTABLE4 and the reply yields a committed response of DATA_SYNC4 or UNSTABLE4 and the reply yields a committed response of DATA_SYNC4 or
UNSTABLE4, the client will follow up some time in the future with a UNSTABLE4, the client will follow up some time in the future with a
COMMIT operation to synchronize outstanding asynchronous data and COMMIT operation to synchronize outstanding asynchronous data and
metadata with the server's stable storage, barring client error. It metadata with the server's stable storage, barring client error. It
is possible that due to client crash or other error that a subsequent is possible that due to client crash or other error that a subsequent
COMMIT will not be received by the server. COMMIT will not be received by the server.
For a WRITE with a stateid value of all bits 0, the server MAY allow For a WRITE using the special anonymous stateid, the server MAY allow
the WRITE to be serviced subject to mandatory file locks or the the WRITE to be serviced subject to mandatory file locks or the
current share deny modes for the file. For a WRITE with a stateid current share deny modes for the file. For a WRITE using the special
value of all bits 1, the server MUST NOT allow the WRITE operation to READ bypass stateid, the server MUST NOT allow the WRITE operation to
bypass locking checks at the server and are treated exactly the same bypass locking checks at the server and is treated exactly the same
as if a stateid of all bits 0 were used. as if the anonymous stateid were used.
On success, the current filehandle retains its value. On success, the current filehandle retains its value.
15.38.5. IMPLEMENTATION 15.38.5. IMPLEMENTATION
It is possible for the server to write fewer bytes of data than It is possible for the server to write fewer bytes of data than
requested by the client. In this case, the server should not return requested by the client. In this case, the server should not return
an error unless no data was written at all. If the server writes an error unless no data was written at all. If the server writes
less than the number of bytes specified, the client should issue less than the number of bytes specified, the client should issue
another WRITE to write the remaining data. another WRITE to write the remaining data.
skipping to change at page 289, line 47 skipping to change at page 292, line 47
SECINFO and therefore its results, an attacker in the middle could SECINFO and therefore its results, an attacker in the middle could
modify results such that the client might select a weaker algorithm modify results such that the client might select a weaker algorithm
in the set allowed by server, making the client and/or server in the set allowed by server, making the client and/or server
vulnerable to further attacks. vulnerable to further attacks.
The second operation that SHOULD use integrity protection is any The second operation that SHOULD use integrity protection is any
GETATTR for the fs_locations attribute. The attack has two steps. GETATTR for the fs_locations attribute. The attack has two steps.
First the attacker modifies the unprotected results of some operation First the attacker modifies the unprotected results of some operation
to return NFS4ERR_MOVED. Second, when the client follows up with a to return NFS4ERR_MOVED. Second, when the client follows up with a
GETATTR for the fs_locations attribute, the attacker modifies the GETATTR for the fs_locations attribute, the attacker modifies the
results to cause the client migrate its traffic to a server results to cause the client to migrate its traffic to a server
controlled by the attacker. controlled by the attacker.
Because the operations SETCLIENTID/SETCLIENTID_CONFIRM are Because the operations SETCLIENTID/SETCLIENTID_CONFIRM are
responsible for the release of client state, it is imperative that responsible for the release of client state, it is imperative that
the principal used for these operations is checked against and match the principal used for these operations is checked against and match
the previous use of these operations. See Section 9.1.1 for further with the previous use of these operations. See Section 9.1.1 for
discussion. further discussion.
Unicode in the form of UTF-8 is used for file component names (i.e., Unicode in the form of UTF-8 is used for file component names (i.e.,
both directory and file components), as well as the owner and both directory and file components), as well as the owner and
owner_group attributes; other character sets may also be allowed for owner_group attributes; other character sets may also be allowed for
file component names. String processing (e.g., Unicode file component names. String processing (e.g., Unicode
normalization) raises security concerns for string comparison - see normalization) raises security concerns for string comparison - see
Sections 5.9 and 12 for further discussion and see [RFC6943] for Sections 5.9 and 12 for further discussion and see [RFC6943] for
related identifier comparison security considerations. File related identifier comparison security considerations. File
component names are identifiers with respect to the identifier component names are identifiers with respect to the identifier
comparison discussion in [RFC6943] because they are used to identify comparison discussion in [RFC6943] because they are used to identify
skipping to change at page 292, line 8 skipping to change at page 295, line 8
[RFC20] Cerf, V., "ASCII format for network interchange", RFC 20, [RFC20] Cerf, V., "ASCII format for network interchange", RFC 20,
October 1969. October 1969.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", March 1997. Requirement Levels", March 1997.
[RFC2203] Eisler, M., Chiu, A., and L. Ling, "RPCSEC_GSS Protocol [RFC2203] Eisler, M., Chiu, A., and L. Ling, "RPCSEC_GSS Protocol
Specification", RFC 2203, September 1997. Specification", RFC 2203, September 1997.
[RFC2279] Yergeau, F., "UTF-8, a transformation format of ISO
10646", RFC 2279, January 1998.
[RFC2743] Linn, J., "Generic Security Service Application Program [RFC2743] Linn, J., "Generic Security Service Application Program
Interface Version 2, Update 1", RFC 2743, January 2000. Interface Version 2, Update 1", RFC 2743, January 2000.
[RFC3490] Faltstrom, P., Hoffman, P., and A. Costello,
"Internationalizing Domain Names in Applications (IDNA)",
RFC 3490, March 2003.
[RFC3492] Costello, A., "Punycode: A Bootstring encoding of Unicode
for Internationalized Domain Names in Applications
(IDNA)", RFC 3492, March 2003.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, November 2003.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226,
May 2008.
[RFC5403] Eisler, M., "RPCSEC_GSS Version 2", RFC 5403, February [RFC5403] Eisler, M., "RPCSEC_GSS Version 2", RFC 5403, February
2009. 2009.
[RFC5531] Thurlow, R., "RPC: Remote Procedure Call Protocol [RFC5531] Thurlow, R., "RPC: Remote Procedure Call Protocol
Specification Version 2", RFC 5531, May 2009. Specification Version 2", RFC 5531, May 2009.
[RFC5665] Eisler, M., Ed., "IANA Considerations for Remote Procedure [RFC5665] Eisler, M., Ed., "IANA Considerations for Remote Procedure
Call (RPC) Network Identifiers and Universal Address Call (RPC) Network Identifiers and Universal Address
Formats", RFC 5665, January 2010. Formats", RFC 5665, January 2010.
skipping to change at page 292, line 35 skipping to change at page 295, line 47
Applications (IDNA): Definitions and Document Framework", Applications (IDNA): Definitions and Document Framework",
RFC 5890, August 2010. RFC 5890, August 2010.
[RFC5891] Klensin, J., "Internationalized Domain Names in [RFC5891] Klensin, J., "Internationalized Domain Names in
Applications (IDNA): Protocol", RFC 5891, August 2010. Applications (IDNA): Protocol", RFC 5891, August 2010.
[RFC6649] Astrand, L. and T. Yu, "Deprecate DES, RC4-HMAC-EXP, and [RFC6649] Astrand, L. and T. Yu, "Deprecate DES, RC4-HMAC-EXP, and
Other Weak Cryptographic Algorithms in Kerberos", RFC Other Weak Cryptographic Algorithms in Kerberos", RFC
6649, July 2012. 6649, July 2012.
[RFC6943] Thaler, D., "Issues in Identifier Comparison for Security
Purposes", RFC 6943, May 2013.
[RFCNFSv4XDR] [RFCNFSv4XDR]
Haynes, T. and D. Noveck, "NFSv4 Version 0 XDR Haynes, T. and D. Noveck, "NFSv4 Version 0 XDR
Description", draft-ietf-nfsv4-rfc3530bis-dot-x-22 (work Description", draft-ietf-nfsv4-rfc3530bis-dot-x-23 (work
in progress), Apr 2014. in progress), Dec 2014.
[SPECIALCASING] [SPECIALCASING]
The Unicode Consortium, "SpecialCasing-6.3.0.txt", Unicode The Unicode Consortium, "SpecialCasing-6.3.0.txt", Unicode
Character Database , September 2013, Character Database , September 2013,
<http://www.unicode.org/Public/6.3.0/ucd/ <http://www.unicode.org/Public/6.3.0/ucd/
SpecialCasing.txt>. SpecialCasing.txt>.
[UNICODE] The Unicode Consortium, "The Unicode Standard, Version [UNICODE] The Unicode Consortium, "The Unicode Standard, Version
6.3.0", September 2013, 6.3.0", September 2013,
<http://www.unicode.org/versions/Unicode6.3.0/>. <http://www.unicode.org/versions/Unicode6.3.0/>.
skipping to change at page 293, line 21 skipping to change at page 296, line 31
19.2. Informative References 19.2. Informative References
[Chet] Juszczak, C., "Improving the Performance and Correctness [Chet] Juszczak, C., "Improving the Performance and Correctness
of an NFS Server", USENIX Conference Proceedings , June of an NFS Server", USENIX Conference Proceedings , June
1990. 1990.
[Floyd] Floyd, S. and V. Jacobson, "The Synchronization of [Floyd] Floyd, S. and V. Jacobson, "The Synchronization of
Periodic Routing Messages", IEEE/ACM Transactions on Periodic Routing Messages", IEEE/ACM Transactions on
Networking 2(2), pp. 122-136, April 1994. Networking 2(2), pp. 122-136, April 1994.
[IESG_errata] [IESG_ERRATA]
IESG, "IESG Processing of RFC Errata for the IETF Stream", IESG, "IESG Processing of RFC Errata for the IETF Stream",
July 2008. July 2008.
[MS-SMB] Microsoft Corporation, , "Server Message Block (SMB)
Protocol Specification", MS-SMB 17.0, November 2009.
[P1003.1e] [P1003.1e]
Institute of Electrical and Electronics Engineers, Inc., Institute of Electrical and Electronics Engineers, Inc.,
"IEEE Draft P1003.1e", 1997. "IEEE Draft P1003.1e", 1997.
[RFC0793] Postel, J., "Transmission Control Protocol", STD 7, RFC [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, RFC
793, September 1981. 793, September 1981.
[RFC1094] Nowicki, B., "NFS: Network File System Protocol [RFC1094] Nowicki, B., "NFS: Network File System Protocol
specification", RFC 1094, March 1989. specification", RFC 1094, March 1989.
skipping to change at page 294, line 22 skipping to change at page 297, line 34
Beame, C., Eisler, M., and D. Noveck, "Network File System Beame, C., Eisler, M., and D. Noveck, "Network File System
(NFS) version 4 Protocol", RFC 3010, December 2000. (NFS) version 4 Protocol", RFC 3010, December 2000.
[RFC3232] Reynolds, J., "Assigned Numbers: RFC 1700 is Replaced by [RFC3232] Reynolds, J., "Assigned Numbers: RFC 1700 is Replaced by
an On-line Database", RFC 3232, January 2002. an On-line Database", RFC 3232, January 2002.
[RFC3530] Shepler, S., Callaghan, B., Robinson, D., Thurlow, R., [RFC3530] Shepler, S., Callaghan, B., Robinson, D., Thurlow, R.,
Beame, C., Eisler, M., and D. Noveck, "Network File System Beame, C., Eisler, M., and D. Noveck, "Network File System
(NFS) version 4 Protocol", RFC 3530, April 2003. (NFS) version 4 Protocol", RFC 3530, April 2003.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, November 2003.
[RFC4121] Zhu, L., Jaganathan, K., and S. Hartman, "The Kerberos [RFC4121] Zhu, L., Jaganathan, K., and S. Hartman, "The Kerberos
Version 5 Generic Security Service Application Program Version 5 Generic Security Service Application Program
Interface (GSS-API) Mechanism: Version 2", RFC 4121, July Interface (GSS-API) Mechanism: Version 2", RFC 4121, July
2005. 2005.
[RFC4178] Zhu, L., Leach, P., Jaganathan, K., and W. Ingersoll, "The [RFC4178] Zhu, L., Leach, P., Jaganathan, K., and W. Ingersoll, "The
Simple and Protected Generic Security Service Application Simple and Protected Generic Security Service Application
Program Interface (GSS-API) Negotiation Mechanism", RFC Program Interface (GSS-API) Negotiation Mechanism", RFC
4178, October 2005. 4178, October 2005.
[RFC4506] Eisler, M., "XDR: External Data Representation Standard", [RFC4506] Eisler, M., "XDR: External Data Representation Standard",
RFC 4506, May 2006. RFC 4506, May 2006.
[RFC4511] Sermersheim, J., "Lightweight Directory Access Protocol [RFC4511] Sermersheim, J., "Lightweight Directory Access Protocol
(LDAP): The Protocol", RFC 4511, June 2006. (LDAP): The Protocol", RFC 4511, June 2006.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226,
May 2008.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246, August 2008. (TLS) Protocol Version 1.2", RFC 5246, August 2008.
[RFC5661] Shepler, S., Eisler, M., and D. Noveck, "Network File [RFC5661] Shepler, S., Eisler, M., and D. Noveck, "Network File
System (NFS) Version 4 Minor Version 1 Protocol", RFC System (NFS) Version 4 Minor Version 1 Protocol", RFC
5661, January 2010. 5661, January 2010.
[RFC6365] Hoffman, P. and J. Klensin, "Terminology Used in [RFC6365] Hoffman, P. and J. Klensin, "Terminology Used in
Internationalization in the IETF", BCP 166, RFC 6365, Internationalization in the IETF", BCP 166, RFC 6365,
September 2011. September 2011.
[RFC6943] Thaler, D., "Issues in Identifier Comparison for Security
Purposes", RFC 6943, May 2013.
[fcntl] The Open Group, "Section 'fcntl()' of System Interfaces of [fcntl] The Open Group, "Section 'fcntl()' of System Interfaces of
The Open Group Base Specifications Issue 6 IEEE Std The Open Group Base Specifications Issue 6 IEEE Std
1003.1, 2004 Edition, HTML Version (www.opengroup.org), 1003.1, 2004 Edition, HTML Version (www.opengroup.org),
ISBN 1931624232", 2004. ISBN 1931624232", 2004.
[fsync] The Open Group, "Section 'fsync()' of System Interfaces of [fsync] The Open Group, "Section 'fsync()' of System Interfaces of
The Open Group Base Specifications Issue 6 IEEE Std The Open Group Base Specifications Issue 6 IEEE Std
1003.1, 2004 Edition, HTML Version (www.opengroup.org), 1003.1, 2004 Edition, HTML Version (www.opengroup.org),
ISBN 1931624232", 2004. ISBN 1931624232", 2004.
skipping to change at page 296, line 46 skipping to change at page 300, line 5
Condition and Courtesy Locks in general. He was also the leading Condition and Courtesy Locks in general. He was also the leading
advocate of stamping out backport issues from [RFC5661]. advocate of stamping out backport issues from [RFC5661].
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.
Benjamin Kaduk reminded us that DES is dead and Nico Williams helped Benjamin Kaduk reminded us that DES is dead and Nico Williams helped
us close the lid on the coffin. us close the lid on the coffin.
Elwyn Davies provided a very thorough and engaging Gen-ART review,
thanks!
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 occurrences 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
 End of changes. 213 change blocks. 
723 lines changed or deleted 812 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/