draft-ietf-nfsv4-rfc3530bis-31.txt   draft-ietf-nfsv4-rfc3530bis-32.txt 
NFSv4 T. Haynes, Ed. NFSv4 T. Haynes, Ed.
Internet-Draft NetApp Internet-Draft NetApp
Obsoletes: 3530 (if approved) D. Noveck, Ed. Obsoletes: 3530 (if approved) D. Noveck, Ed.
Intended status: Standards Track February 13, 2014 Intended status: Standards Track March 04, 2014
Expires: August 17, 2014 Expires: September 5, 2014
Network File System (NFS) Version 4 Protocol Network File System (NFS) Version 4 Protocol
draft-ietf-nfsv4-rfc3530bis-31.txt draft-ietf-nfsv4-rfc3530bis-32.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 49 skipping to change at page 1, line 49
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on August 17, 2014. This Internet-Draft will expire on September 5, 2014.
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 3, line 37 skipping to change at page 3, line 37
3.2. Security Flavors . . . . . . . . . . . . . . . . . . . . 26 3.2. Security Flavors . . . . . . . . . . . . . . . . . . . . 26
3.2.1. Security mechanisms for NFSv4 . . . . . . . . . . . 26 3.2.1. Security mechanisms for NFSv4 . . . . . . . . . . . 26
3.3. Security Negotiation . . . . . . . . . . . . . . . . . . 27 3.3. Security Negotiation . . . . . . . . . . . . . . . . . . 27
3.3.1. SECINFO . . . . . . . . . . . . . . . . . . . . . . 28 3.3.1. SECINFO . . . . . . . . . . . . . . . . . . . . . . 28
3.3.2. Security Error . . . . . . . . . . . . . . . . . . . 28 3.3.2. Security Error . . . . . . . . . . . . . . . . . . . 28
3.3.3. Callback RPC Authentication . . . . . . . . . . . . 28 3.3.3. Callback RPC Authentication . . . . . . . . . . . . 28
4. Filehandles . . . . . . . . . . . . . . . . . . . . . . . . . 29 4. Filehandles . . . . . . . . . . . . . . . . . . . . . . . . . 29
4.1. Obtaining the First Filehandle . . . . . . . . . . . . . 29 4.1. Obtaining the First Filehandle . . . . . . . . . . . . . 29
4.1.1. Root Filehandle . . . . . . . . . . . . . . . . . . 30 4.1.1. Root Filehandle . . . . . . . . . . . . . . . . . . 30
4.1.2. Public Filehandle . . . . . . . . . . . . . . . . . 30 4.1.2. Public Filehandle . . . . . . . . . . . . . . . . . 30
4.2. Filehandle Types . . . . . . . . . . . . . . . . . . . . 31 4.2. Filehandle Types . . . . . . . . . . . . . . . . . . . . 30
4.2.1. General Properties of a Filehandle . . . . . . . . . 31 4.2.1. General Properties of a Filehandle . . . . . . . . . 31
4.2.2. Persistent Filehandle . . . . . . . . . . . . . . . 32 4.2.2. Persistent Filehandle . . . . . . . . . . . . . . . 31
4.2.3. Volatile Filehandle . . . . . . . . . . . . . . . . 32 4.2.3. Volatile Filehandle . . . . . . . . . . . . . . . . 32
4.2.4. One Method of Constructing a Volatile Filehandle . . 33 4.2.4. One Method of Constructing a Volatile Filehandle . . 33
4.3. Client Recovery from Filehandle Expiration . . . . . . . 34 4.3. Client Recovery from Filehandle Expiration . . . . . . . 34
5. Attributes . . . . . . . . . . . . . . . . . . . . . . . . . 35 5. Attributes . . . . . . . . . . . . . . . . . . . . . . . . . 34
5.1. REQUIRED Attributes . . . . . . . . . . . . . . . . . . 36 5.1. REQUIRED Attributes . . . . . . . . . . . . . . . . . . 36
5.2. RECOMMENDED Attributes . . . . . . . . . . . . . . . . . 36 5.2. RECOMMENDED Attributes . . . . . . . . . . . . . . . . . 36
5.3. Named Attributes . . . . . . . . . . . . . . . . . . . . 37 5.3. Named Attributes . . . . . . . . . . . . . . . . . . . . 36
5.4. Classification of Attributes . . . . . . . . . . . . . . 38 5.4. Classification of Attributes . . . . . . . . . . . . . . 38
5.5. Set-Only and Get-Only Attributes . . . . . . . . . . . . 39 5.5. Set-Only and Get-Only Attributes . . . . . . . . . . . . 39
5.6. REQUIRED Attributes - List and Definition References . . 39 5.6. REQUIRED Attributes - List and Definition References . . 39
5.7. RECOMMENDED Attributes - List and Definition 5.7. RECOMMENDED Attributes - List and Definition
References . . . . . . . . . . . . . . . . . . . . . . . 40 References . . . . . . . . . . . . . . . . . . . . . . . 40
5.8. Attribute Definitions . . . . . . . . . . . . . . . . . 41 5.8. Attribute Definitions . . . . . . . . . . . . . . . . . 41
5.8.1. Definitions of REQUIRED Attributes . . . . . . . . . 41 5.8.1. Definitions of REQUIRED Attributes . . . . . . . . . 41
5.8.2. Definitions of Uncategorized RECOMMENDED 5.8.2. Definitions of Uncategorized RECOMMENDED
Attributes . . . . . . . . . . . . . . . . . . . . . 43 Attributes . . . . . . . . . . . . . . . . . . . . . 43
5.9. Interpreting owner and owner_group . . . . . . . . . . . 49 5.9. Interpreting owner and owner_group . . . . . . . . . . . 49
skipping to change at page 12, line 45 skipping to change at page 12, line 45
directory or file and referred to by a string name. Named attributes directory or file and referred to by a string name. Named attributes
are meant to be used by client applications as a method to associate are meant to be used by client applications as a method to associate
application-specific data with a regular file or directory. NFSv4.1 application-specific data with a regular file or directory. NFSv4.1
modifies named attributes relative to NFSv4.0 by tightening the modifies named attributes relative to NFSv4.0 by tightening the
allowed operations in order to prevent the development of non- allowed operations in order to prevent the development of non-
interoperable implementations. Named attributes are discussed in interoperable implementations. Named attributes are discussed in
Section 5.3. Section 5.3.
1.3.3.3. Multi-server Namespace 1.3.3.3. Multi-server Namespace
NFSv4 contains a number of features to allow implementation of A single-server namespace is the file system hierarchy that the
namespaces that cross server boundaries and that allow and facilitate server presents for remote access. It is a proper subset of all the
a non-disruptive transfer of support for individual file systems file systems available locally. NFSv4 contains a number of features
between servers. They are all based upon attributes that allow one to allow implementation of namespaces that cross server boundaries
file system to specify alternate or new locations for that file and that allow and facilitate a non-disruptive transfer of support
system. for individual file systems between servers. They are all based upon
attributes that allow one file system to specify alternative or new
locations for that file system. I.e., just as a client might
traverse across local file systems on a single server, it can now
traverse to a remote file system on a different server.
These attributes may be used together with the concept of absent file These attributes may be used together with the concept of absent file
systems, which provide specifications for additional locations but no systems, which provide specifications for additional locations but no
actual file system content. This allows a number of important actual file system content. This allows a number of important
facilities: facilities:
o Location attributes may be used with absent file systems to o Location attributes may be used with absent file systems to
implement referrals whereby one server may direct the client to a implement referrals whereby one server may direct the client to a
file system provided by another server. This allows extensive file system provided by another server. This allows extensive
multi-server namespaces to be constructed. multi-server namespaces to be constructed.
o Location attributes may be provided for present file systems to o Location attributes may be provided for present file systems to
provide the locations of alternate file system instances or provide the locations of alternative file system instances or
replicas to be used in the event that the current file system replicas to be used in the event that the current file system
instance becomes unavailable. instance becomes unavailable.
o Location attributes may be provided when a previously present file o Location attributes may be provided when a previously present file
system becomes absent. This allows non-disruptive migration of system becomes absent. This allows non-disruptive migration of
file systems to alternate 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 can be combined. The CLOSE operation also provides
for the release of state accumulated by OPEN. 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). The state associated with file locks is Lock Manager (NLM) [RFC1813]. The state associated with file locks
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
the client does not renew its lease within the defined period, all the client does not renew its lease within the defined period, all
state associated with the client's lease may be released by the state associated with the client's lease may be released by the
server. The client may renew its lease with use of the RENEW server. The client may renew its lease with use of the RENEW
operation or implicitly by use of other operations (primarily READ). operation or implicitly by use of other operations (primarily READ).
1.3.6. Client Caching and Delegation 1.3.6. Client Caching and Delegation
The file, attribute, and directory caching for the NFSv4 protocol is The file, attribute, and directory caching for the NFSv4 protocol is
similar to previous versions. Attributes and directory information similar to previous versions. Attributes and directory information
skipping to change at page 19, line 9 skipping to change at page 19, line 9
| 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. |
| 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 |
| | GSS_Init_sec_context. See [RFC2743] for | | | GSS_Init_sec_context. See [RFC2743] for |
| | details. | | | details. |
| seqid4 | typedef uint32_t seqid4; | | seqid4 | typedef uint32_t seqid4; |
| | Sequence identifier used for file locking. | | | Sequence identifier used for file locking. |
| utf8string | typedef opaque utf8string<>; | | utf8string | typedef opaque utf8string<>; |
| | UTF-8 encoding for strings. | | | UTF-8 encoding for strings. |
| utf8str_cis | typedef utf8string utf8str_cis; | | utf8str_cis | typedef utf8string utf8str_cis; |
| | Case-insensitive UTF-8 string. | | | Case-insensitive UTF-8 string. |
| utf8str_cs | typedef utf8string utf8str_cs; | | utf8str_cs | typedef utf8string utf8str_cs; |
| | Case-sensitive UTF-8 string. | | | Case-sensitive UTF-8 string. |
| utf8str_mixed | typedef utf8string utf8str_mixed; | | utf8str_mixed | typedef utf8string utf8str_mixed; |
skipping to change at page 24, line 39 skipping to change at page 24, line 39
Historically, NFSv2 and NFSv3 servers have resided on port 2049. The Historically, NFSv2 and NFSv3 servers have resided on port 2049. The
registered port 2049 [RFC3232] for the NFS protocol SHOULD be the registered port 2049 [RFC3232] for the NFS protocol SHOULD be the
default configuration. Using the registered port for NFS services default configuration. Using the registered port for NFS services
means the NFS client will not need to use the RPC binding protocols means the NFS client will not need to use the RPC binding protocols
as described in [RFC1833]; this will allow NFS to transit firewalls. as described in [RFC1833]; this will allow NFS to transit firewalls.
Where an NFSv4 implementation supports operation over the IP network Where an NFSv4 implementation supports operation over the IP network
protocol, the supported transport layer between NFS and IP MUST be an protocol, the supported transport layer between NFS and IP MUST be an
IETF standardised transport protocol that is specified to avoid IETF standardised transport protocol that is specified to avoid
network congestion; such transports include TCP and SCTP. To enhance network congestion; such transports include TCP and Stream Control
the possibilities for interoperability, an NFSv4 implementation MUST Transmission Protocol (SCTP). To enhance the possibilities for
support operation over the TCP transport protocol, at least until interoperability, an NFSv4 implementation MUST support operation over
such time as a standards track RFC revises this requirement to use a the TCP transport protocol.
different IETF standardised transport protocol with appropriate
congestion control.
If TCP is used as the transport, the client and server SHOULD use If TCP is used as the transport, the client and server SHOULD use
persistent connections. This will prevent the weakening of TCP's persistent connections. This will prevent the weakening of TCP's
congestion control via short lived connections and will improve congestion control via short lived connections and will improve
performance for the Wide Area Network (WAN) environment by performance for the Wide Area Network (WAN) environment by
eliminating the need for SYN handshakes. eliminating the need for SYN handshakes.
To date, all NFSv4 implementations are TCP based, i.e., there are
none for SCTP nor UDP. UDP by itself is not sufficient as a
transport for NFSv4, neither is UDP in combination with some other
mechanism (e.g., DCCP [RFC4340], NORM [RFC5740]).
As noted in Section 17, the authentication model for NFSv4 has moved As noted in Section 17, the authentication model for NFSv4 has moved
from machine-based to principal-based. However, this modification of from machine-based to principal-based. However, this modification of
the authentication model does not imply a technical requirement to the authentication model does not imply a technical requirement to
move the TCP connection management model from whole machine-based to move the TCP connection management model from whole machine-based to
one based on a per user model. In particular, NFS over TCP client one based on a per user model. In particular, NFS over TCP client
implementations have traditionally multiplexed traffic for multiple implementations have traditionally multiplexed traffic for multiple
users over a common TCP connection between an NFS client and server. users over a common TCP connection between an NFS client and server.
This has been true, regardless of whether the NFS client is using This has been true, regardless of whether the NFS client is using
AUTH_SYS, AUTH_DH, RPCSEC_GSS or any other flavor. Similarly, NFS AUTH_SYS, AUTH_DH, RPCSEC_GSS or any other flavor. Similarly, NFS
over TCP server implementations have assumed such a model and thus over TCP server implementations have assumed such a model and thus
skipping to change at page 26, line 18 skipping to change at page 26, line 14
3.2. Security Flavors 3.2. Security Flavors
Traditional RPC implementations have included AUTH_NONE, AUTH_SYS, Traditional RPC implementations have included AUTH_NONE, AUTH_SYS,
AUTH_DH, and AUTH_KRB4 as security flavors. With [RFC2203] an AUTH_DH, and AUTH_KRB4 as security flavors. With [RFC2203] an
additional security flavor of RPCSEC_GSS has been introduced which additional security flavor of RPCSEC_GSS has been introduced which
uses the functionality of GSS-API [RFC2743]. This allows for the use uses the functionality of GSS-API [RFC2743]. This allows for the use
of various security mechanisms by the RPC layer without the of various security mechanisms by the RPC layer without the
additional implementation overhead of adding RPC security flavors. additional implementation overhead of adding RPC security flavors.
For NFSv4, the RPCSEC_GSS security flavor MUST be used to enable the For NFSv4, the RPCSEC_GSS security flavor MUST be used to enable the
mandatory security mechanism. Other flavors, such as, AUTH_NONE, mandatory to implement security mechanism. Other flavors, such as,
AUTH_SYS, and AUTH_DH MAY be implemented as well. AUTH_NONE, AUTH_SYS, and AUTH_DH MAY be implemented as well.
3.2.1. Security mechanisms for NFSv4 3.2.1. Security mechanisms for NFSv4
RPCSEC_GSS, via GSS-API, supports multiple mechanisms that provide RPCSEC_GSS, via GSS-API, supports multiple mechanisms that provide
security services. For interoperability, NFSv4 clients and servers security services. For interoperability, NFSv4 clients and servers
MUST support the Kerberos V5 security mechanism. MUST support the Kerberos V5 security mechanism.
The use of RPCSEC_GSS requires selection of mechanism, quality of The use of RPCSEC_GSS requires selection of mechanism, quality of
protection (QOP), and service (authentication, integrity, privacy). protection (QOP), and service (authentication, integrity, privacy).
For the mandated security mechanisms, NFSv4 specifies that a QOP of For the mandated security mechanisms, NFSv4 specifies that a QOP of
skipping to change at page 28, line 4 skipping to change at page 27, line 40
or server, so there is some due diligence required by the user of or server, so there is some due diligence required by the user of
NFSv4 to ensure that security is acceptable where needed. Guidance NFSv4 to ensure that security is acceptable where needed. Guidance
is provided in [RFC6649] as to why weak algorithms should be disabled is provided in [RFC6649] as to why weak algorithms should be disabled
by default. by default.
3.3. Security Negotiation 3.3. Security Negotiation
With the NFSv4 server potentially offering multiple security With the NFSv4 server potentially offering multiple security
mechanisms, the client needs a method to determine or negotiate which mechanisms, the client needs a method to determine or negotiate which
mechanism is to be used for its communication with the server. The mechanism is to be used for its communication with the server. The
NFS server may have multiple points within its file system name space NFS server can have multiple points within its file system name space
that are available for use by NFS clients. In turn the NFS server that are available for use by NFS clients. In turn the NFS server
may be configured such that each of these entry points may have can be configured such that each of these entry points can have
different or multiple security mechanisms in use. different or multiple security mechanisms in use.
The security negotiation between client and server SHOULD be done The security negotiation between client and server SHOULD be done
with a secure channel to eliminate the possibility of a third party with a secure channel to eliminate the possibility of a third party
intercepting the negotiation sequence and forcing the client and intercepting the negotiation sequence and forcing the client and
server to choose a lower level of security than required or desired. server to choose a lower level of security than required or desired.
See Section 17 for further discussion. See Section 17 for further discussion.
3.3.1. SECINFO 3.3.1. SECINFO
skipping to change at page 28, line 32 skipping to change at page 28, line 22
It is possible that the server's policies change during the client's It is possible that the server's policies change during the client's
interaction therefore forcing the client to negotiate a new security interaction therefore forcing the client to 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 may receive an NFS error of communication with the server, the client can receive an NFS error of
NFS4ERR_WRONGSEC. This error allows the server to notify the client NFS4ERR_WRONGSEC. This error allows the server to notify the client
that the security triple currently being used is not appropriate for that the security triple currently being used is not appropriate for
access to the server's file system resources. The client is then access to the server's file system resources. The client is then
responsible for determining what security triples are available at responsible for determining what security triples are available at
the server and choose one which is appropriate for the client. See the server and 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
skipping to change at page 31, line 8 skipping to change at page 30, line 41
and the ROOT filehandle refer to the same file system object. and the ROOT filehandle refer to the same file system object.
However, it is up to the administrative software at the server and However, it is up to the administrative software at the server and
the policies of the server administrator to define the binding of the the policies of the server administrator to define the binding of the
PUBLIC filehandle and server file system object. The client may not PUBLIC filehandle and server file system object. The client may not
make any assumptions about this binding. The client uses the PUBLIC make any assumptions about this binding. The client uses the PUBLIC
filehandle via the PUTPUBFH operation. filehandle via the PUTPUBFH operation.
4.2. Filehandle Types 4.2. Filehandle Types
In the NFSv2 and NFSv3 protocols, there was one type of filehandle In the NFSv2 and NFSv3 protocols, there was one type of filehandle
with a single set of semantics. This type of filehandle is termed with a single set of semantics, of which the primary one was that it
"persistent" in NFS Version 4. The semantics of a persistent was peristent across a server reboot. As such, this type of
filehandle remain the same as before. A new type of filehandle filehandle is termed "persistent" in NFS Version 4. The semantics of
introduced in NFS Version 4 is the "volatile" filehandle, which a persistent filehandle remain the same as before. A new type of
attempts to accommodate certain server environments. filehandle introduced in NFS Version 4 is the "volatile" filehandle,
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
file system may not provide the invariant or the server's file system file system may not provide the invariant or the server's file system
programming interfaces may not provide access to the needed programming interfaces may not provide access to the needed
invariant. Volatile filehandles may ease the implementation of invariant. Volatile filehandles may ease the implementation of
server functionality such as hierarchical storage management or file server functionality such as hierarchical storage management or file
skipping to change at page 36, line 28 skipping to change at page 36, line 16
not the underlying file system at the server has a named attribute not the underlying file system at the server has a named attribute
directory. Therefore, operations such as SETATTR and GETATTR on the directory. Therefore, operations such as SETATTR and GETATTR on the
named attribute directory are undefined. named attribute directory are undefined.
5.1. REQUIRED Attributes 5.1. REQUIRED Attributes
These MUST be supported by every NFSv4.0 client and server in order These MUST be supported by every NFSv4.0 client and server in order
to ensure a minimum level of interoperability. The server MUST store to ensure a minimum level of interoperability. The server MUST store
and return these attributes, and the client MUST be able to function and return these attributes, and the client MUST be able to function
with an attribute set limited to these attributes. With just the with an attribute set limited to these attributes. With just the
REQUIRED attributes some client functionality may be impaired or REQUIRED attributes some client functionality can be impaired or
limited in some ways. A client may ask for any of these attributes limited in some ways. A client can ask for any of these attributes
to be returned by setting a bit in the GETATTR request, and the to be returned by setting a bit in the GETATTR request, and the
server MUST return their value. server MUST return their value.
5.2. RECOMMENDED Attributes 5.2. RECOMMENDED Attributes
These attributes are understood well enough to warrant support in the These attributes are understood well enough to warrant support in the
NFSv4.0 protocol. However, they may not be supported on all clients NFSv4.0 protocol. However, they may not be supported on all clients
and servers. A client MAY ask for any of these attributes to be and servers. A client MAY ask for any of these attributes to be
returned by setting a bit in the GETATTR request but must handle the returned by setting a bit in the GETATTR request but MUST handle the
case where the server does not return them. A client MAY ask for the case where the server does not return them. A client MAY ask for the
set of attributes the server supports and SHOULD NOT request set of attributes the server supports and SHOULD NOT request
attributes the server does not support. A server should be tolerant attributes the server does not support. A server should be tolerant
of requests for unsupported attributes and simply not return them of requests for unsupported attributes and simply not return them
rather than considering the request an error. It is expected that rather than considering the request an error. It is expected that
servers will support all attributes they comfortably can and only servers will support all attributes they comfortably can and only
fail to support attributes that are difficult to support in their fail to support attributes that are difficult to support in their
operating environments. A server should provide attributes whenever operating environments. A server should provide attributes whenever
they don't have to "tell lies" to the client. For example, a file they don't have to "tell lies" to the client. For example, a file
modification time should be either an accurate time or should not be modification time should be either an accurate time or should not be
skipping to change at page 79, line 25 skipping to change at page 79, line 25
accessible via normal namespace operations (e.g., LOOKUP). In this accessible via normal namespace operations (e.g., LOOKUP). In this
case, the file system is said to be "present" at that position in the case, the file system is said to be "present" at that position in the
namespace, and clients will typically use it, reserving use of namespace, and clients will typically use it, reserving use of
additional locations specified via the location-related attributes to additional locations specified via the location-related attributes to
situations in which the principal location is no longer available. situations in which the principal location is no longer available.
When there is no actual file system at the namespace location in When there is no actual file system at the namespace location in
question, the file system is said to be "absent". An absent file question, the file system is said to be "absent". An absent file
system contains no files or directories other than the root. Any system contains no files or directories other than the root. Any
reference to it, except to access a small set of attributes useful in reference to it, except to access a small set of attributes useful in
determining alternate locations, will result in an error, determining alternative locations, will result in an error,
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
skipping to change at page 82, line 19 skipping to change at page 82, line 19
facilities in providing reliable, manageable, and scalable data facilities in providing reliable, manageable, and scalable data
access. access.
When a file system is present, these attributes can provide When a file system is present, these attributes can provide
alternative locations, to be used to access the same data, in the alternative locations, to be used to access the same data, in the
event of server failures, communications problems, or other event of server failures, communications problems, or other
difficulties that make continued access to the current file system difficulties that make continued access to the current file system
impossible or otherwise impractical. Under some circumstances, impossible or otherwise impractical. Under some circumstances,
multiple alternative locations may be used simultaneously to provide multiple alternative locations may be used simultaneously to provide
higher-performance access to the file system in question. Provision higher-performance access to the file system in question. Provision
of such alternate locations is referred to as "replication" although of such alternative locations is referred to as "replication"
there are cases in which replicated sets of data are not in fact although there are cases in which replicated sets of data are not in
present, and the replicas are instead different paths to the same fact present, and the replicas are instead different paths to the
data. same data.
When a file system is present and becomes absent, clients can be When a file system is present and becomes absent, clients can be
given the opportunity to have continued access to their data, at an given the opportunity to have continued access to their data, at an
alternate location. In this case, a continued attempt to use the alternative location. In this case, a continued attempt to use the
data in the now-absent file system will result in an NFS4ERR_MOVED data in the now-absent file system will result in an NFS4ERR_MOVED
error and, at that point, the successor locations (typically only one error and, at that point, the successor locations (typically only one
although multiple choices are possible) can be fetched and used to although multiple choices are possible) can be fetched and used to
continue access. Transfer of the file system contents to the new continue access. Transfer of the file system contents to the new
location is referred to as "migration", but it should be kept in mind location is referred to as "migration", but it should be kept in mind
that there are cases in which this term can be used, like that there are cases in which this term can be used, like
"replication", when there is no actual data migration per se. "replication", when there is no actual data migration per se.
Where a file system was not previously present, specification of file Where a file system was not previously present, specification of file
system location provides a means by which file systems located on one system location provides a means by which file systems located on one
skipping to change at page 82, line 51 skipping to change at page 82, line 51
Because client support for location-related attributes is OPTIONAL, a Because client support for location-related attributes is OPTIONAL, a
server may (but is not required to) take action to hide migration and server may (but is not required to) take action to hide migration and
referral events from such clients, by acting as a proxy, for example. referral events from such clients, by acting as a proxy, for example.
8.4.1. File System Replication 8.4.1. File System Replication
The fs_locations attribute provides alternative locations, to be used The fs_locations attribute provides alternative locations, to be used
to access data in place of or in addition to the current file system to access data in place of or in addition to the current file system
instance. On first access to a file system, the client should obtain instance. On first access to a file system, the client should obtain
the value of the set of alternate locations by interrogating the the value of the set of alternative locations by interrogating the
fs_locations attribute. fs_locations attribute.
In the event that server failures, communications problems, or other In the event that server failures, communications problems, or other
difficulties make continued access to the current file system difficulties make continued access to the current file system
impossible or otherwise impractical, the client can use the alternate impossible or otherwise impractical, the client can use the
locations as a way to get continued access to its data. Multiple alternative locations as a way to get continued access to its data.
locations may be used simultaneously, to provide higher performance Multiple locations may be used simultaneously, to provide higher
through the exploitation of multiple paths between client and target performance through the exploitation of multiple paths between client
file system. and target file system.
The alternate locations may be physical replicas of the (typically The alternative locations may be physical replicas of the (typically
read-only) file system data, or they may reflect alternate paths to read-only) file system data, or they may reflect alternative paths to
the same server or provide for the use of various forms of server the same server or provide for the use of various forms of server
clustering in which multiple servers provide alternate ways of clustering in which multiple servers provide alternative ways of
accessing the same physical file system. How these different modes accessing the same physical file system. How these different modes
of file system transition are represented within the fs_locations of file system transition are represented within the fs_locations
attribute and how the client deals with file system transition issues attribute and how the client deals with file system transition issues
will be discussed in detail below. will be discussed in detail below.
Multiple server addresses, whether they are derived from a single Multiple server addresses, whether they are derived from a single
entry with a DNS name representing a set of IP addresses or from entry with a DNS name representing a set of IP addresses or from
multiple entries each with its own server address, may correspond to multiple entries each with its own server address, may correspond to
the same actual server. the same actual server.
8.4.2. File System Migration 8.4.2. File System Migration
When a file system is present and becomes absent, clients can be When a file system is present and becomes absent, clients can be
given the opportunity to have continued access to their data, at an given the opportunity to have continued access to their data, at an
alternate location, as specified by the fs_locations attribute. alternative location, as specified by the fs_locations attribute.
Typically, a client will be accessing the file system in question, Typically, a client will be accessing the file system in question,
get an NFS4ERR_MOVED error, and then use the fs_locations attribute get an NFS4ERR_MOVED error, and then use the fs_locations attribute
to determine the new location of the data. to determine the new location of the data.
Such migration can be helpful in providing load balancing or general Such migration can be helpful in providing load balancing or general
resource reallocation. The protocol does not specify how the file resource reallocation. The protocol does not specify how the file
system will be moved between servers. It is anticipated that a system will be moved between servers. It is anticipated that a
number of different server-to-server transfer mechanisms might be number of different server-to-server transfer mechanisms might be
used with the choice left to the server implementor. The NFSv4 used with the choice left to the server implementor. The NFSv4
protocol specifies the method used to communicate the migration event protocol specifies the method used to communicate the migration event
between client and server. between client and server.
The new location may be an alternate communication path to the same The new location may be an alternative communication path to the same
server or, in the case of various forms of server clustering, another server or, in the case of various forms of server clustering, another
server providing access to the same physical file system. The server providing access to the same physical file system. The
client's responsibilities in dealing with this transition depend on client's responsibilities in dealing with this transition depend on
the specific nature of the new access path as well as how and whether the 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.
When an alternate location is designated as the target for migration, When an alternative location is designated as the target for
it must designate the same data. Where file systems are writable, a migration, it must designate the same data. Where file systems are
change made on the original file system must be visible on all writable, a change made on the original file system must be visible
migration targets. Where a file system is not writable but on all migration targets. Where a file system is not writable but
represents a read-only copy (possibly periodically updated) of a represents a read-only copy (possibly periodically updated) of a
writable file system, similar requirements apply to the propagation writable file system, similar requirements apply to the propagation
of updates. Any change visible in the original file system must of updates. Any change visible in the original file system must
already be effected on all migration targets, to avoid any already be effected on all migration targets, to avoid any
possibility that a client, in effecting a transition to the migration possibility that a client, in effecting a transition to the migration
target, will see any reversion in file system state. target, will see any reversion in file system state.
8.4.3. Referrals 8.4.3. Referrals
Referrals provide a way of placing a file system in a location within Referrals provide a way of placing a file system in a location within
skipping to change at page 85, line 17 skipping to change at page 85, line 17
As mentioned above, a single location entry may have a server address As mentioned above, a single location entry may have a server address
target in the form of a DNS name that may represent multiple IP target in the form of a DNS name that may represent multiple IP
addresses, while multiple location entries may have their own server addresses, while multiple location entries may have their own server
address targets that reference the same server. address targets that reference the same server.
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 alternate 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 cannot assume that these addresses are multiple paths to
the same server. In most cases, they will be, but the client MUST the same server. In most cases, they will be, but the client MUST
verify that before acting on that assumption. When two server 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
skipping to change at page 86, line 36 skipping to change at page 86, line 36
NFS4ERR_BAD_STATEID when the client uses those stateids on the new NFS4ERR_BAD_STATEID when the client uses those stateids on the new
server. server.
The server MUST return NFS4ERR_STALE_STATEID when the client uses The server MUST return NFS4ERR_STALE_STATEID when the client uses
those stateids on the old server, regardless of whether migration has those stateids on the old server, regardless of whether migration has
occurred or not. occurred or not.
8.7. Effecting File System Referrals 8.7. Effecting File System Referrals
Referrals are effected when an absent file system is encountered, and Referrals are effected when an absent file system is encountered, and
one or more alternate locations are made available by the one or more alternative locations are made available by the
fs_locations attribute. The client will typically get an fs_locations attribute. The client will typically get an
NFS4ERR_MOVED error, fetch the appropriate location information, and NFS4ERR_MOVED error, fetch the appropriate location information, and
proceed to access the file system on a different server, even though proceed to access the file system on a different server, even though
it retains its logical position within the original namespace. it retains its logical position within the original namespace.
Referrals differ from migration events in that they happen only when Referrals differ from migration events in that they happen only when
the client has not previously referenced the file system in question the client has not previously referenced the file system in question
(so there is nothing to transition). Referrals can only come into (so there is nothing to transition). Referrals can only come into
effect when an absent file system is encountered at its root. effect when an absent file system is encountered at its root.
The examples given in the sections below are somewhat artificial in The examples given in the sections below are somewhat artificial in
skipping to change at page 94, line 15 skipping to change at page 94, line 15
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
is simply the pathname the client used to reach the object on the is simply the pathname the client used to reach the object on the
current server (i.e., the object to which the fs_locations attribute current server (i.e., the object to which the fs_locations attribute
applies). applies).
When the fs_locations attribute is interrogated and there are no When the fs_locations attribute is interrogated and there are no
alternate file system locations, the server SHOULD return a zero- alternative file system locations, the server SHOULD return a zero-
length array of fs_location4 structures, together with a valid length array of fs_location4 structures, together with a valid
fs_root. fs_root.
As an example, suppose there is a replicated file system located at As an example, suppose there is a replicated file system located at
two servers (servA and servB). At servA, the file system is located two servers (servA and servB). At servA, the file system is located
at path /a/b/c. At, servB the file system is located at path /x/y/z. at path /a/b/c. At, servB the file system is located at path /x/y/z.
If the client were to obtain the fs_locations value for the directory If the client were to obtain the fs_locations value for the directory
at /a/b/c/d, it might not necessarily know that the file system's at /a/b/c/d, it might not necessarily know that the file system's
root is located in servA's namespace at /a/b/c. When the client root is located in servA's namespace at /a/b/c. When the client
switches to servB, it will need to determine that the directory it switches to servB, it will need to determine that the directory it
skipping to change at page 132, line 34 skipping to change at page 132, line 34
network distance of the clients that will be accessing the server's network distance of the clients that will be accessing the server's
resources. It is expected that the lease period will take into resources. It is expected that the lease period will take into
account the network propagation delays and other network delay account the network propagation delays and other network delay
factors for the client population. Since the protocol does not allow factors for the client population. Since the protocol does not allow
for an automatic method to determine an appropriate lease period, the for an automatic method to determine an appropriate lease period, the
server's administrator may have to tune the lease period. server's administrator may have to tune the lease period.
9.14. Migration, Replication and State 9.14. Migration, Replication and State
When responsibility for handling a given file system is transferred When responsibility for handling a given file system is transferred
to a new server (migration) or the client chooses to use an alternate to a new server (migration) or the client chooses to use an
server (e.g., in response to server unresponsiveness) in the context alternative server (e.g., in response to server unresponsiveness) in
of file system replication, the appropriate handling of state shared the context of file system replication, the appropriate handling of
between the client and server (i.e., locks, leases, stateids, and state shared between the client and server (i.e., locks, leases,
client IDs) is as described below. The handling differs between stateids, and client IDs) is as described below. The handling
migration and replication. For related discussion of file server differs between migration and replication. For related discussion of
state and recover of such see the sections under Section 9.6. file server state and recover of such see the sections under
Section 9.6.
If a server replica or a server immigrating a file system agrees to, If a server replica or a server immigrating a file system agrees to,
or is expected to, accept opaque values from the client that or is expected to, accept opaque values from the client that
originated from another server, then servers SHOULD encode the originated from another server, then servers SHOULD encode the
"opaque" values in network byte order. This way, servers acting as "opaque" values in network byte order. This way, servers acting as
replicas or immigrating file systems will be able to parse values replicas or immigrating file systems will be able to parse values
like stateids, directory cookies, filehandles, etc. even if their like stateids, directory cookies, filehandles, etc. even if their
native byte order is different from other servers cooperating in the native byte order is different from other servers cooperating in the
replication and migration of the file system. replication and migration of the file system.
skipping to change at page 296, line 15 skipping to change at page 296, line 15
[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, Interface (GSS-API) Mechanism: Version 2", RFC 4121,
July 2005. July 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", Program Interface (GSS-API) Negotiation Mechanism",
RFC 4178, October 2005. RFC 4178, October 2005.
[RFC4340] Kohler, E., Handley, M., and S. Floyd, "Datagram
Congestion Control Protocol (DCCP)", RFC 4340, March 2006.
[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 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226, IANA Considerations Section in RFCs", BCP 26, RFC 5226,
May 2008. 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", System (NFS) Version 4 Minor Version 1 Protocol",
RFC 5661, January 2010. RFC 5661, January 2010.
[RFC5740] Adamson, B., Bormann, C., Handley, M., and J. Macker,
"Negative-acknowledgment (NACK)-Oriented Reliable
Multicast (NORM) Transport Protocol", RFC 5740,
November 2009.
[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.
 End of changes. 38 change blocks. 
84 lines changed or deleted 75 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/