rfc8881v1.xml   rfc8881.xml 
<?xml version='1.0' encoding='utf-8'?> <?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE rfc SYSTEM "rfc2629-xhtml.ent"> <!DOCTYPE rfc SYSTEM "rfc2629-xhtml.ent">
<rfc xmlns:xi="http://www.w3.org/2001/XInclude" category="std" docName="draft-ietf-nfsv4-rfc5661sesqui-msns-04" number="8881" obsoletes="5661" ipr="pre5378Trust200902" updates="" submissionType="IETF" consensus="true" xml:lang="en" tocInclude="true" tocDepth="2" symRefs="false" sortRefs="false" version="3"> <rfc xmlns:xi="http://www.w3.org/2001/XInclude" category="std" docName="draft-ietf-nfsv4-rfc5661sesqui-msns-04" number="8881" obsoletes="5661" ipr="pre5378Trust200902" updates="" submissionType="IETF" consensus="true" xml:lang="en" tocInclude="true" tocDepth="2" symRefs="false" sortRefs="false" version="3">
<!-- [rfced] Throughout the XML file, we see various notes about copyright,
for example:
[auth] Copyright (C) The IETF Trust (2007-2008)
[auth] Copyright (C) The Internet Society (2006)
It is not clear to us why these notes are included. May we remove these
notes?
<!-- xml2rfc v2v3 conversion 2.41.0 --> <!-- xml2rfc v2v3 conversion 2.41.0 -->
<front> <front>
<title abbrev="NFSv4.1 with Namespace Update "> <title abbrev="NFSv4.1 with Namespace Update ">
Network File System (NFS) Version 4 Minor Version 1 Protocol Network File System (NFS) Version 4 Minor Version 1 Protocol
</title> </title>
<seriesInfo name="RFC" value="8881"/> <seriesInfo name="RFC" value="8881"/>
<author fullname="David Noveck" initials="D." surname="Noveck" role="editor"> <author fullname="David Noveck" initials="D." surname="Noveck" role="editor">
<organization abbrev="NetApp">NetApp</organization> <organization abbrev="NetApp">NetApp</organization>
<address> <address>
skipping to change at line 50 skipping to change at line 41
<street>1015 Granger Avenue</street> <street>1015 Granger Avenue</street>
<city>Ann Arbor</city> <city>Ann Arbor</city>
<region>MI</region> <region>MI</region>
<code>48104</code> <code>48104</code>
<country>United States of America</country> <country>United States of America</country>
</postal> </postal>
<phone>+1-248-614-5091</phone> <phone>+1-248-614-5091</phone>
<email>chuck.lever@oracle.com</email> <email>chuck.lever@oracle.com</email>
</address> </address>
</author> </author>
<date month="July" year="2020"/> <date month="August" year="2020"/>
<area>Transport</area> <area>Transport</area>
<workgroup>NFSv4</workgroup> <workgroup>NFSv4</workgroup>
<!-- [rfced] Please provide any keywords (beyond those that
appear in the title) for use on https://www.rfc-editor.org/search
<keyword>example</keyword> <keyword>example</keyword>
<abstract> <abstract>
<t> <t>
This document describes the Network File System (NFS) version 4 This document describes the Network File System (NFS) version 4
minor version 1, minor version 1,
including features retained from the base protocol (NFS version 4 minor including features retained from the base protocol (NFS version 4 minor
version 0, which is specified in RFC 7530) and protocol version 0, which is specified in RFC 7530) and protocol
extensions made subsequently. The later minor version extensions made subsequently. The later minor version
has no dependencies on NFS version 4 minor version 0, and has no dependencies on NFS version 4 minor version 0, and
is considered a separate protocol. is considered a separate protocol.
skipping to change at line 165 skipping to change at line 153
This will involve making changes to consensus decisions reflected This will involve making changes to consensus decisions reflected
in RFC 5661, in situations in which the working group has decided that in RFC 5661, in situations in which the working group has decided that
the treatment in RFC 5661 is incorrect and needs to be revised to the treatment in RFC 5661 is incorrect and needs to be revised to
reflect the working group's new consensus and to ensure compatibility reflect the working group's new consensus and to ensure compatibility
with existing implementations that do not follow the handling with existing implementations that do not follow the handling
described in RFC 5661. described in RFC 5661.
</t> </t>
<t> <t>
Note that it is expected that all such errata reports will remain Note that it is expected that all such errata reports will remain
relevant to implementors and the authors of an eventual rfc5661bis, relevant to implementors and the authors of an eventual rfc5661bis,
despite the fact that this document, when approved, despite the fact that this document
will obsolete RFC 5661 <xref target="RFC5661" format="default"/>. obsoletes RFC 5661 <xref target="RFC5661" format="default"/>.
</t> </t>
</li> </li>
<li> <li>
There is a need for a new approach to the description of There is a need for a new approach to the description of
internationalization since the current internationalization section internationalization since the current internationalization section
(<xref target="internationalization" format="default"/>) has never been (<xref target="internationalization" format="default"/>) has never been
implemented and does implemented and does
not meet the needs of the NFSv4 protocol. Possible solutions are not meet the needs of the NFSv4 protocol. Possible solutions are
to create a new internationalization section modeled on that in to create a new internationalization section modeled on that in
<xref target="RFC7530" format="default"/> or to create a new document describing <xref target="RFC7530" format="default"/> or to create a new document describing
skipping to change at line 918 skipping to change at line 906
<section anchor="Core_Infrastructure" numbered="true" toc="default"> <section anchor="Core_Infrastructure" numbered="true" toc="default">
<name>Core Infrastructure</name> <name>Core Infrastructure</name>
<section anchor="Introduction" numbered="true" toc="default"> <section anchor="Introduction" numbered="true" toc="default">
<name>Introduction</name> <name>Introduction</name>
<t> <t>
NFSv4.1 relies on core infrastructure common to nearly NFSv4.1 relies on core infrastructure common to nearly
every operation. This core infrastructure is described in the remainder every operation. This core infrastructure is described in the remainder
of this section. of this section.
</t> </t>
</section> </section>
<!-- [auth] Introduction -->
<section anchor="RPC_and_XDR" numbered="true" toc="default"> <section anchor="RPC_and_XDR" numbered="true" toc="default">
<name>RPC and XDR</name> <name>RPC and XDR</name>
<t> <t>
The NFSv4.1 protocol is a Remote Procedure Call (RPC) The NFSv4.1 protocol is a Remote Procedure Call (RPC)
application that uses RPC version 2 and the corresponding eXternal application that uses RPC version 2 and the corresponding eXternal
Data Representation (XDR) as defined in Data Representation (XDR) as defined in
<xref target="RFC5531" format="default"/> and <xref target="RFC5531" format="default"/> and
<xref target="RFC4506" format="default"/>. <xref target="RFC4506" format="default"/>.
</t> </t>
skipping to change at line 1009 skipping to change at line 996
this allows RPCSEC_GSS to offer per-RPC authentication and this allows RPCSEC_GSS to offer per-RPC authentication and
identity. See <xref target="RFC2203" format="default"/> for more information. identity. See <xref target="RFC2203" format="default"/> for more information.
</t> </t>
<t> <t>
NFSv4.1 client and servers <bcp14>MUST</bcp14> support RPCSEC_GSS's integrity and authentication NFSv4.1 client and servers <bcp14>MUST</bcp14> support RPCSEC_GSS's integrity and authentication
service. NFSv4.1 servers <bcp14>MUST</bcp14> support RPCSEC_GSS's privacy service. service. NFSv4.1 servers <bcp14>MUST</bcp14> support RPCSEC_GSS's privacy service.
NFSv4.1 clients <bcp14>SHOULD</bcp14> support RPCSEC_GSS's privacy service. NFSv4.1 clients <bcp14>SHOULD</bcp14> support RPCSEC_GSS's privacy service.
</t> </t>
</section> </section>
<!-- [auth] Identity, Authentication, Integrity, Privacy -->
<section anchor="security_mechs" numbered="true" toc="default"> <section anchor="security_mechs" numbered="true" toc="default">
<name>Security Mechanisms for NFSv4.1</name> <name>Security Mechanisms for NFSv4.1</name>
<t> <t>
RPCSEC_GSS, via GSS-API, normalizes access to mechanisms that RPCSEC_GSS, via GSS-API, normalizes access to mechanisms that
provide security services. Therefore, NFSv4.1 clients and servers provide security services. Therefore, NFSv4.1 clients and servers
<bcp14>MUST</bcp14> support the Kerberos V5 security mechanism. <bcp14>MUST</bcp14> support the Kerberos V5 security mechanism.
</t> </t>
<t> <t>
The use of RPCSEC_GSS requires selection of mechanism, The use of RPCSEC_GSS requires selection of mechanism,
skipping to change at line 1089 skipping to change at line 1075
<t> <t>
When deploying NFSv4.1, the strength of the security achieved depends When deploying NFSv4.1, the strength of the security achieved depends
on the existing Kerberos V5 infrastructure. The algorithms on the existing Kerberos V5 infrastructure. The algorithms
of Kerberos V5 are not directly exposed to or selectable by the of Kerberos V5 are not directly exposed to or selectable by the
client or server, so there is some due diligence required by client or server, so there is some due diligence required by
the user of NFSv4.1 to ensure that security is acceptable the user of NFSv4.1 to ensure that security is acceptable
where needed. where needed.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] Kerberos V5 -->
</section> </section>
<!-- [auth] Security mechanisms for NFSv4.1 -->
<section anchor="GSS_Server_Principal" numbered="true" toc="default"> <section anchor="GSS_Server_Principal" numbered="true" toc="default">
<name>GSS Server Principal</name> <name>GSS Server Principal</name>
<t> <t>
Regardless of what security mechanism under RPCSEC_GSS Regardless of what security mechanism under RPCSEC_GSS
is being used, the NFS server <bcp14>MUST</bcp14> identify itself is being used, the NFS server <bcp14>MUST</bcp14> identify itself
in GSS-API via a GSS_C_NT_HOSTBASED_SERVICE name type. in GSS-API via a GSS_C_NT_HOSTBASED_SERVICE name type.
GSS_C_NT_HOSTBASED_SERVICE names are of the form: GSS_C_NT_HOSTBASED_SERVICE names are of the form:
</t> </t>
<artwork name="" type="" align="left" alt=""><![CDATA[ <artwork name="" type="" align="left" alt=""><![CDATA[
skipping to change at line 1120 skipping to change at line 1104
]]></artwork> ]]></artwork>
<t> <t>
Implementations of security mechanisms will convert Implementations of security mechanisms will convert
nfs@hostname to various different forms. For Kerberos nfs@hostname to various different forms. For Kerberos
V5, the following form is <bcp14>RECOMMENDED</bcp14>: V5, the following form is <bcp14>RECOMMENDED</bcp14>:
</t> </t>
<artwork name="" type="" align="left" alt=""><![CDATA[ <artwork name="" type="" align="left" alt=""><![CDATA[
nfs/hostname nfs/hostname
]]></artwork> ]]></artwork>
</section> </section>
<!-- [auth] GSS Server Principal -->
</section> </section>
<!-- [auth] RPCSEC_GSS and Security Services -->
</section> </section>
<!-- [auth] RPC Security Flavors -->
</section> </section>
<!-- [auth] RPC-based Security -->
</section> </section>
<!-- [auth] RPC and XDR -->
<section anchor="COMPOUND_and_CB_COMPOUND" numbered="true" toc="default"> <section anchor="COMPOUND_and_CB_COMPOUND" numbered="true" toc="default">
<name>COMPOUND and CB_COMPOUND</name> <name>COMPOUND and CB_COMPOUND</name>
<t> <t>
A significant departure from the versions of the NFS A significant departure from the versions of the NFS
protocol before NFSv4 is the introduction of the protocol before NFSv4 is the introduction of the
COMPOUND procedure. For the NFSv4 protocol, COMPOUND procedure. For the NFSv4 protocol,
in all minor versions, there are exactly two RPC procedures, in all minor versions, there are exactly two RPC procedures,
NULL and COMPOUND. The COMPOUND procedure is defined NULL and COMPOUND. The COMPOUND procedure is defined
as a series of individual operations and these operations as a series of individual operations and these operations
skipping to change at line 1186 skipping to change at line 1165
subsequent minor versions. subsequent minor versions.
</t> </t>
<t> <t>
Except for a small number of operations needed for session Except for a small number of operations needed for session
creation, server requests and callback requests are performed creation, server requests and callback requests are performed
within the context of a session. Sessions provide a client within the context of a session. Sessions provide a client
context for every request and support robust replay context for every request and support robust replay
protection for non-idempotent requests. protection for non-idempotent requests.
</t> </t>
</section> </section>
<!-- [auth] COMPOUND and CB_COMPOUND -->
<section anchor="Client_Identifiers" numbered="true" toc="default"> <section anchor="Client_Identifiers" numbered="true" toc="default">
<name>Client Identifiers and Client Owners</name> <name>Client Identifiers and Client Owners</name>
<t> <t>
For each operation that obtains or depends on locking state, the For each operation that obtains or depends on locking state, the
specific client needs to be identifiable by the server. specific client needs to be identifiable by the server.
</t> </t>
<t> <t>
Each distinct client instance is represented Each distinct client instance is represented
skipping to change at line 1243 skipping to change at line 1221
cannot be done, for any of a number of reasons, the locking state cannot be done, for any of a number of reasons, the locking state
will remain for a time subject to lease expiration will remain for a time subject to lease expiration
(see <xref target="lease_renewal" format="default"/>) (see <xref target="lease_renewal" format="default"/>)
and the new client will need to wait for and the new client will need to wait for
such state to be removed, if it makes conflicting lock requests. such state to be removed, if it makes conflicting lock requests.
</t> </t>
<t> <t>
Client identification is encapsulated in the following client owner Client identification is encapsulated in the following client owner
data type: data type:
</t> </t>
<!-- [rfced] Please review whether the "type" attribute should <sourcecode type="xdr"><![CDATA[
be set for <sourcecode> elements in the XML file. If the current
list of preferred values for "type"
(https://www.rfc-editor.org/materials/sourcecode-types.txt) does not
contain an applicable type, then feel free to suggest a new one.
It is also acceptable to leave the "type" attribute not set.
<sourcecode type=""><![CDATA[
struct client_owner4 { struct client_owner4 {
verifier4 co_verifier; verifier4 co_verifier;
opaque co_ownerid<NFS4_OPAQUE_LIMIT>; opaque co_ownerid<NFS4_OPAQUE_LIMIT>;
}; };
]]></sourcecode> ]]></sourcecode>
<t> <t>
The first field, co_verifier, is a client incarnation The first field, co_verifier, is a client incarnation
verifier, allowing the server to distinguish successive incarnations verifier, allowing the server to distinguish successive incarnations
(e.g., reboots) of the same client. The server will start the process of (e.g., reboots) of the same client. The server will start the process of
canceling the client's leased state if co_verifier canceling the client's leased state if co_verifier
skipping to change at line 1484 skipping to change at line 1455
burden as if the server had failed and restarted. burden as if the server had failed and restarted.
Typically, a server would not release a client ID Typically, a server would not release a client ID
unless there had been no activity from that client unless there had been no activity from that client
for many minutes. As long as there are sessions, for many minutes. As long as there are sessions,
opens, locks, delegations, layouts, or wants, the opens, locks, delegations, layouts, or wants, the
server <bcp14>MUST NOT</bcp14> release the client ID. See <xref target="loss_of_session" format="default"/> for discussion on server <bcp14>MUST NOT</bcp14> release the client ID. See <xref target="loss_of_session" format="default"/> for discussion on
releasing inactive sessions. releasing inactive sessions.
</t> </t>
</section> </section>
<!-- [auth] Server Release of Client ID -->
<section anchor="cowner_conflicts" numbered="true" toc="default"> <section anchor="cowner_conflicts" numbered="true" toc="default">
<name>Resolving Client Owner Conflicts</name> <name>Resolving Client Owner Conflicts</name>
<t> <t>
When the server gets an EXCHANGE_ID for a client owner that When the server gets an EXCHANGE_ID for a client owner that
currently has no state, or that has state but the lease has expired, currently has no state, or that has state but the lease has expired,
the server <bcp14>MUST</bcp14> allow the the server <bcp14>MUST</bcp14> allow the
EXCHANGE_ID and confirm the new client ID if followed by the EXCHANGE_ID and confirm the new client ID if followed by the
appropriate CREATE_SESSION. appropriate CREATE_SESSION.
</t> </t>
<t> <t>
skipping to change at line 1566 skipping to change at line 1536
confirms the client ID, the server deletes state. confirms the client ID, the server deletes state.
If the co_verifier values are the same (e.g., the If the co_verifier values are the same (e.g., the
client either is updating properties of the client ID client either is updating properties of the client ID
(<xref target="OP_EXCHANGE_ID" format="default"/>) or (<xref target="OP_EXCHANGE_ID" format="default"/>) or
is attempting trunking (<xref target="Trunking" format="default"/>), is attempting trunking (<xref target="Trunking" format="default"/>),
the server <bcp14>MUST NOT</bcp14> delete state. the server <bcp14>MUST NOT</bcp14> delete state.
</t> </t>
</section> </section>
<!-- [auth] Handling Client Owner Conflicts -->
</section> </section>
<!-- [auth] Client Identifiers -->
<section anchor="Server_Owners" numbered="true" toc="default"> <section anchor="Server_Owners" numbered="true" toc="default">
<name>Server Owners</name> <name>Server Owners</name>
<t> <t>
The server owner is similar to a client owner The server owner is similar to a client owner
(<xref target="Client_Identifiers" format="default"/>), but unlike the (<xref target="Client_Identifiers" format="default"/>), but unlike the
client owner, there is no shorthand server ID. client owner, there is no shorthand server ID.
The server owner is defined in the following data type: The server owner is defined in the following data type:
</t> </t>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct server_owner4 { struct server_owner4 {
uint64_t so_minor_id; uint64_t so_minor_id;
opaque so_major_id<NFS4_OPAQUE_LIMIT>; opaque so_major_id<NFS4_OPAQUE_LIMIT>;
}; };
]]></sourcecode> ]]></sourcecode>
<t> <t>
The server owner is returned from The server owner is returned from
EXCHANGE_ID. When the so_major_id fields are the same in EXCHANGE_ID. When the so_major_id fields are the same in
two EXCHANGE_ID results, the connections that each EXCHANGE_ID two EXCHANGE_ID results, the connections that each EXCHANGE_ID
were sent over can be assumed to address the same server were sent over can be assumed to address the same server
skipping to change at line 1610 skipping to change at line 1578
The considerations for generating an so_major_id are The considerations for generating an so_major_id are
similar to that for generating a co_ownerid string (see similar to that for generating a co_ownerid string (see
<xref target="Client_Identifiers" format="default"/>). The consequences <xref target="Client_Identifiers" format="default"/>). The consequences
of two servers generating conflicting so_major_id values of two servers generating conflicting so_major_id values
are less dire than they are for co_ownerid conflicts are less dire than they are for co_ownerid conflicts
because the client can use RPCSEC_GSS to compare the because the client can use RPCSEC_GSS to compare the
authenticity of each server authenticity of each server
(see <xref target="Trunking" format="default"/>). (see <xref target="Trunking" format="default"/>).
</t> </t>
</section> </section>
<!-- [auth] Server Owners -->
<section anchor="Security_Service_Negotiation" numbered="true" toc="default"> <section anchor="Security_Service_Negotiation" numbered="true" toc="default">
<name>Security Service Negotiation</name> <name>Security Service Negotiation</name>
<t> <t>
With the NFSv4.1 server potentially offering With the NFSv4.1 server potentially offering
multiple security mechanisms, the client needs a method multiple security mechanisms, the client needs a method
to determine or negotiate which mechanism is to be to determine or negotiate which mechanism is to be
used for its communication with the server. The NFS used for its communication with the server. The NFS
server may have multiple points within its file system server may have multiple points within its file system
namespace that are available for use by NFS clients. namespace that are available for use by NFS clients.
skipping to change at line 1647 skipping to change at line 1614
<name>NFSv4.1 Security Tuples</name> <name>NFSv4.1 Security Tuples</name>
<t> <t>
An NFS server can assign one or more "security tuples" to each An NFS server can assign one or more "security tuples" to each
security policy boundary in its namespace. Each security tuple security policy boundary in its namespace. Each security tuple
consists of a security flavor consists of a security flavor
(see <xref target="RPC_Security_Flavors" format="default"/>) and, if the flavor (see <xref target="RPC_Security_Flavors" format="default"/>) and, if the flavor
is RPCSEC_GSS, a GSS-API mechanism Object Identifier (OID), a GSS-API quality of is RPCSEC_GSS, a GSS-API mechanism Object Identifier (OID), a GSS-API quality of
protection, and an RPCSEC_GSS service. protection, and an RPCSEC_GSS service.
</t> </t>
</section> </section>
<!-- [auth] NFSv4.1 Security Tuples -->
<section anchor="SECINFO_and_SECINFO_NO_NAME" numbered="true" toc="default"> <section anchor="SECINFO_and_SECINFO_NO_NAME" numbered="true" toc="default">
<name>SECINFO and SECINFO_NO_NAME</name> <name>SECINFO and SECINFO_NO_NAME</name>
<t> <t>
The SECINFO and SECINFO_NO_NAME operations allow the client to The SECINFO and SECINFO_NO_NAME operations allow the client to
determine, on a per-filehandle basis, what security tuple is to be determine, on a per-filehandle basis, what security tuple is to be
used for server access. In general, the client will not have to used for server access. In general, the client will not have to
use either operation except during initial communication with the use either operation except during initial communication with the
server or when the client crosses security policy boundaries at the server or when the client crosses security policy boundaries at the
server. However, the server's policies may also change at any time server. However, the server's policies may also change at any time
skipping to change at line 1672 skipping to change at line 1638
access that would be allowed if a request was sent over the same access that would be allowed if a request was sent over the same
connection used for the SECINFO or SECINFO_NO_NAME operation connection used for the SECINFO or SECINFO_NO_NAME operation
(e.g., read-only vs. read-write) access, security tuples that allow (e.g., read-only vs. read-write) access, security tuples that allow
greater access should be presented first. Where the general level greater access should be presented first. Where the general level
of access is the same and different security flavors limit the of access is the same and different security flavors limit the
range of principals whose privileges are recognized (e.g., allowing range of principals whose privileges are recognized (e.g., allowing
or disallowing root access), flavors supporting the greatest range or disallowing root access), flavors supporting the greatest range
of principals should be listed first. of principals should be listed first.
</t> </t>
</section> </section>
<!-- [auth] SECINFO and SECINFO_NO_NAME -->
<section anchor="Security_Error" numbered="true" toc="default"> <section anchor="Security_Error" numbered="true" toc="default">
<name>Security Error</name> <name>Security Error</name>
<t> <t>
Based on the assumption that each NFSv4.1 client Based on the assumption that each NFSv4.1 client
and server <bcp14>MUST</bcp14> support a minimum set of security (i.e., and server <bcp14>MUST</bcp14> support a minimum set of security (i.e.,
Kerberos V5 under RPCSEC_GSS), Kerberos V5 under RPCSEC_GSS),
the NFS client will initiate file access to the server the NFS client will initiate file access to the server
with one of the minimal security tuples. During with one of the minimal security tuples. During
communication with the server, the client may receive an communication with the server, the client may receive an
skipping to change at line 1719 skipping to change at line 1684
The client is saving a filehandle for a future The client is saving a filehandle for a future
RESTOREFH, LINK, or RENAME. SAVEFH <bcp14>MUST NOT</bcp14> RESTOREFH, LINK, or RENAME. SAVEFH <bcp14>MUST NOT</bcp14>
return NFS4ERR_WRONGSEC. To determine whether or not the put return NFS4ERR_WRONGSEC. To determine whether or not the put
filehandle operation returns NFS4ERR_WRONGSEC, filehandle operation returns NFS4ERR_WRONGSEC,
the server implementation pretends SAVEFH is not in the server implementation pretends SAVEFH is not in
the series of operations and examines which of the the series of operations and examines which of the
situations described in the other subsections of <xref target="putfh_series" format="default"/> apply. situations described in the other subsections of <xref target="putfh_series" format="default"/> apply.
</t> </t>
</section> </section>
<!-- [auth] Put Filehandle Operation + SAVEFH -->
<section anchor="PUTFHplusPUTFH" numbered="true" toc="default"> <section anchor="PUTFHplusPUTFH" numbered="true" toc="default">
<name>Two or More Put Filehandle Operations</name> <name>Two or More Put Filehandle Operations</name>
<t> <t>
For a series of N put filehandle operations, the server For a series of N put filehandle operations, the server
<bcp14>MUST NOT</bcp14> return NFS4ERR_WRONGSEC to the first N-1 put <bcp14>MUST NOT</bcp14> return NFS4ERR_WRONGSEC to the first N-1 put
filehandle operations. filehandle operations.
The Nth put filehandle operation The Nth put filehandle operation
is handled as if it is the first in a subseries of is handled as if it is the first in a subseries of
operations. operations.
For example, if the For example, if the
server received a COMPOUND request with this series of server received a COMPOUND request with this series of
operations -- PUTFH, PUTROOTFH, LOOKUP -- then the operations -- PUTFH, PUTROOTFH, LOOKUP -- then the
PUTFH operation is ignored for NFS4ERR_WRONGSEC purposes, and the PUTFH operation is ignored for NFS4ERR_WRONGSEC purposes, and the
PUTROOTFH, LOOKUP subseries is processed as according PUTROOTFH, LOOKUP subseries is processed as according
to <xref target="PUTFHplusLOOKUP" format="default"/>. to <xref target="PUTFHplusLOOKUP" format="default"/>.
</t> </t>
</section> </section>
<!-- [auth] PUTFH + PUTFH -->
<section anchor="PUTFHplusLOOKUP" numbered="true" toc="default"> <section anchor="PUTFHplusLOOKUP" numbered="true" toc="default">
<name>Put Filehandle Operation + LOOKUP (or OPEN of an Existing Name)</name> <name>Put Filehandle Operation + LOOKUP (or OPEN of an Existing Name)</name>
<t> <t>
This situation also applies to a put filehandle operation followed This situation also applies to a put filehandle operation followed
by a LOOKUP or an OPEN operation that specifies an existing component name. by a LOOKUP or an OPEN operation that specifies an existing component name.
</t> </t>
<t> <t>
In this situation, the client is potentially crossing In this situation, the client is potentially crossing
a security policy boundary, and the set of security tuples a security policy boundary, and the set of security tuples
the parent directory supports may differ from those of the parent directory supports may differ from those of
skipping to change at line 1808 skipping to change at line 1771
could have changed since the could have changed since the
time the filehandle was obtained. time the filehandle was obtained.
</t> </t>
<t> <t>
Therefore, an NFSv4.1 server <bcp14>MUST NOT</bcp14> return NFS4ERR_WRONGSEC Therefore, an NFSv4.1 server <bcp14>MUST NOT</bcp14> return NFS4ERR_WRONGSEC
in response to the put filehandle operation in response to the put filehandle operation
if the operation if the operation
is immediately followed by a LOOKUP or an OPEN by component name. is immediately followed by a LOOKUP or an OPEN by component name.
</t> </t>
</section> </section>
<!-- [auth] PUTFH + LOOKUP -->
<section anchor="PUTFHplusLOOKUPP" numbered="true" toc="default"> <section anchor="PUTFHplusLOOKUPP" numbered="true" toc="default">
<name>Put Filehandle Operation + LOOKUPP</name> <name>Put Filehandle Operation + LOOKUPP</name>
<t> <t>
Since SECINFO only works its way down, there is no way LOOKUPP can Since SECINFO only works its way down, there is no way LOOKUPP can
return NFS4ERR_WRONGSEC without SECINFO_NO_NAME. SECINFO_NO_NAME return NFS4ERR_WRONGSEC without SECINFO_NO_NAME. SECINFO_NO_NAME
solves this issue via style solves this issue via style
SECINFO_STYLE4_PARENT, which works in the opposite direction as SECINFO. SECINFO_STYLE4_PARENT, which works in the opposite direction as SECINFO.
As with <xref target="PUTFHplusLOOKUP" format="default"/>, a put filehandle operation As with <xref target="PUTFHplusLOOKUP" format="default"/>, a put filehandle operation
that is followed by a LOOKUPP that is followed by a LOOKUPP
skipping to change at line 1832 skipping to change at line 1794
LOOKUPP, GETFH sequence LOOKUPP, GETFH sequence
of operations with every security tuple it supports. of operations with every security tuple it supports.
</t> </t>
<t> <t>
Regardless of whether SECINFO_NO_NAME is supported, an Regardless of whether SECINFO_NO_NAME is supported, an
NFSv4.1 server <bcp14>MUST NOT</bcp14> return NFS4ERR_WRONGSEC in NFSv4.1 server <bcp14>MUST NOT</bcp14> return NFS4ERR_WRONGSEC in
response to a put filehandle operation if the response to a put filehandle operation if the
operation is immediately followed by a LOOKUPP. operation is immediately followed by a LOOKUPP.
</t> </t>
</section> </section>
<!-- [auth] PUTFH + LOOKUPP -->
<section anchor="PUTFHplusSECINFO" numbered="true" toc="default"> <section anchor="PUTFHplusSECINFO" numbered="true" toc="default">
<name>Put Filehandle Operation + SECINFO/SECINFO_NO_NAME</name> <name>Put Filehandle Operation + SECINFO/SECINFO_NO_NAME</name>
<t> <t>
A security-sensitive client is allowed to choose A security-sensitive client is allowed to choose
a strong security tuple when querying a server to a strong security tuple when querying a server to
determine a file object's permitted security tuples. determine a file object's permitted security tuples.
The security tuple chosen by the client does not have The security tuple chosen by the client does not have
to be included in the tuple list of the security policy to be included in the tuple list of the security policy
of either the parent directory indicated in the put filehandle of either the parent directory indicated in the put filehandle
skipping to change at line 1865 skipping to change at line 1826
the <bcp14>REQUIRED</bcp14> set. the <bcp14>REQUIRED</bcp14> set.
</t> </t>
<t> <t>
The NFSv4.1 server <bcp14>MUST NOT</bcp14> return NFS4ERR_WRONGSEC to a The NFSv4.1 server <bcp14>MUST NOT</bcp14> return NFS4ERR_WRONGSEC to a
put filehandle operation that put filehandle operation that
is immediately followed by SECINFO or SECINFO_NO_NAME. is immediately followed by SECINFO or SECINFO_NO_NAME.
The NFSv4.1 server <bcp14>MUST NOT</bcp14> return NFS4ERR_WRONGSEC from SECINFO or The NFSv4.1 server <bcp14>MUST NOT</bcp14> return NFS4ERR_WRONGSEC from SECINFO or
SECINFO_NO_NAME. SECINFO_NO_NAME.
</t> </t>
</section> </section>
<!-- [auth] PUTFH + SECINFO -->
<section anchor="PUTFHplusNothing" numbered="true" toc="default"> <section anchor="PUTFHplusNothing" numbered="true" toc="default">
<name>Put Filehandle Operation + Nothing</name> <name>Put Filehandle Operation + Nothing</name>
<t> <t>
The NFSv4.1 server <bcp14>MUST NOT</bcp14> return NFS4ERR_WRONGSEC. The NFSv4.1 server <bcp14>MUST NOT</bcp14> return NFS4ERR_WRONGSEC.
</t> </t>
</section> </section>
<!-- [auth] PUTFH + Nothing -->
<section anchor="PUTFHplusAnythingElse" numbered="true" toc="default"> <section anchor="PUTFHplusAnythingElse" numbered="true" toc="default">
<name>Put Filehandle Operation + Anything Else</name> <name>Put Filehandle Operation + Anything Else</name>
<t> <t>
"Anything Else" includes OPEN by filehandle. "Anything Else" includes OPEN by filehandle.
</t> </t>
<t> <t>
The security policy enforcement applies to the The security policy enforcement applies to the
filehandle specified in the put filehandle operation. Therefore, the filehandle specified in the put filehandle operation. Therefore, the
put filehandle operation <bcp14>MUST</bcp14> put filehandle operation <bcp14>MUST</bcp14>
skipping to change at line 1901 skipping to change at line 1860
operation + SECINFO_NO_NAME (style SECINFO_STYLE4_CURRENT_FH) is an operation + SECINFO_NO_NAME (style SECINFO_STYLE4_CURRENT_FH) is an
efficient way for the client to recover from efficient way for the client to recover from
NFS4ERR_WRONGSEC. NFS4ERR_WRONGSEC.
</t> </t>
<t> <t>
The NFSv4.1 server <bcp14>MUST NOT</bcp14> return NFS4ERR_WRONGSEC to The NFSv4.1 server <bcp14>MUST NOT</bcp14> return NFS4ERR_WRONGSEC to
any operation other than a put filehandle operation, any operation other than a put filehandle operation,
LOOKUP, LOOKUPP, and OPEN (by component name). LOOKUP, LOOKUPP, and OPEN (by component name).
</t> </t>
</section> </section>
<!-- [auth] PUTFH + Anything Else -->
<section anchor="aftersecinfo" numbered="true" toc="default"> <section anchor="aftersecinfo" numbered="true" toc="default">
<name>Operations after SECINFO and SECINFO_NO_NAME</name> <name>Operations after SECINFO and SECINFO_NO_NAME</name>
<t> <t>
Suppose a client sends a COMPOUND procedure Suppose a client sends a COMPOUND procedure
containing the series SEQUENCE, PUTFH, containing the series SEQUENCE, PUTFH,
SECINFO_NONAME, READ, and suppose the security tuple SECINFO_NONAME, READ, and suppose the security tuple
used does not match that required for the target used does not match that required for the target
file. By rule (see <xref target="PUTFHplusSECINFO" format="default"/>), file. By rule (see <xref target="PUTFHplusSECINFO" format="default"/>),
neither PUTFH nor SECINFO_NO_NAME can neither PUTFH nor SECINFO_NO_NAME can
return NFS4ERR_WRONGSEC. By rule (see <xref target="PUTFHplusAnythingElse" format="default"/>), READ cannot return return NFS4ERR_WRONGSEC. By rule (see <xref target="PUTFHplusAnythingElse" format="default"/>), READ cannot return
NFS4ERR_WRONGSEC. The issue is resolved by the fact NFS4ERR_WRONGSEC. The issue is resolved by the fact
that SECINFO and SECINFO_NO_NAME consume the current that SECINFO and SECINFO_NO_NAME consume the current
filehandle (note that this is a change from NFSv4.0). This leaves no current filehandle for filehandle (note that this is a change from NFSv4.0). This leaves no current filehandle for
READ to use, and READ returns NFS4ERR_NOFILEHANDLE. READ to use, and READ returns NFS4ERR_NOFILEHANDLE.
</t> </t>
</section> </section>
<!-- [auth] Operations after SECINFO and SECINFO_NO_NAME" -->
</section> </section>
<section anchor="link_rename" numbered="true" toc="default"> <section anchor="link_rename" numbered="true" toc="default">
<name>LINK and RENAME</name> <name>LINK and RENAME</name>
<t> <t>
The LINK and RENAME operations use both the current The LINK and RENAME operations use both the current
and saved filehandles. and saved filehandles.
Technically, the server <bcp14>MAY</bcp14> return NFS4ERR_WRONGSEC from Technically, the server <bcp14>MAY</bcp14> return NFS4ERR_WRONGSEC from
LINK or RENAME LINK or RENAME
if the security policy of the if the security policy of the
skipping to change at line 1978 skipping to change at line 1935
The server can return NFS4ERR_XDEV. The server can return NFS4ERR_XDEV.
</li> </li>
<li> <li>
The server can The server can
allow the security policy of the current filehandle to allow the security policy of the current filehandle to
override that of the saved filehandle, and so return NFS4_OK. override that of the saved filehandle, and so return NFS4_OK.
</li> </li>
</ul> </ul>
</section> </section>
</section> </section>
<!-- [auth] Using NFS4ERR_WRONGSEC, SECINFO, and SECINFO_NO_NAME -->
</section> </section>
<!-- [auth] Security Error -->
</section> </section>
<!-- [auth] Security Service Negotiation -->
<section anchor="minor_versioning" numbered="true" toc="default"> <section anchor="minor_versioning" numbered="true" toc="default">
<name>Minor Versioning</name> <name>Minor Versioning</name>
<t> <t>
To address the requirement of an NFS protocol that can evolve as the To address the requirement of an NFS protocol that can evolve as the
need arises, the NFSv4.1 protocol contains the rules and need arises, the NFSv4.1 protocol contains the rules and
framework to allow for future minor changes or versioning. framework to allow for future minor changes or versioning.
</t> </t>
<t> <t>
The base assumption with respect to minor versioning is that any The base assumption with respect to minor versioning is that any
skipping to change at line 2156 skipping to change at line 2110
to be <bcp14>RECOMMENDED</bcp14> or <bcp14>OPTIONAL</bcp14> complicates implementation of the minor version. to be <bcp14>RECOMMENDED</bcp14> or <bcp14>OPTIONAL</bcp14> complicates implementation of the minor version.
</t> </t>
</li> </li>
<li> <li>
A client <bcp14>MUST NOT</bcp14> attempt to use a stateid, filehandle, or similar A client <bcp14>MUST NOT</bcp14> attempt to use a stateid, filehandle, or similar
returned object from the COMPOUND procedure with minor version X for returned object from the COMPOUND procedure with minor version X for
another COMPOUND procedure with minor version Y, where X != Y. another COMPOUND procedure with minor version Y, where X != Y.
</li> </li>
</ol> </ol>
</section> </section>
<!-- [auth] Minor Versioning -->
<section anchor="Non-RPC-based_Security_Services" numbered="true" toc="default"> <section anchor="Non-RPC-based_Security_Services" numbered="true" toc="default">
<name>Non-RPC-Based Security Services</name> <name>Non-RPC-Based Security Services</name>
<t> <t>
As described in <xref target="Authentication_Integrity_Privacy" format="default"/>, As described in <xref target="Authentication_Integrity_Privacy" format="default"/>,
NFSv4.1 relies on RPC for identification, NFSv4.1 relies on RPC for identification,
authentication, integrity, and privacy. NFSv4.1 itself authentication, integrity, and privacy. NFSv4.1 itself
provides or enables additional security services as described in the provides or enables additional security services as described in the
next several subsections. next several subsections.
</t> </t>
skipping to change at line 2185 skipping to change at line 2138
operations. operations.
</t> </t>
<t> <t>
Principals with appropriate access rights can modify the Principals with appropriate access rights can modify the
authorization on a file object via the SETATTR authorization on a file object via the SETATTR
(<xref target="OP_SETATTR" format="default"/>) operation. Attributes that affect (<xref target="OP_SETATTR" format="default"/>) operation. Attributes that affect
access rights include mode, owner, owner_group, acl, dacl, and access rights include mode, owner, owner_group, acl, dacl, and
sacl. See <xref target="file_attributes" format="default"/>. sacl. See <xref target="file_attributes" format="default"/>.
</t> </t>
</section> </section>
<!-- [auth] Authorization -->
<section anchor="Auditing" numbered="true" toc="default"> <section anchor="Auditing" numbered="true" toc="default">
<name>Auditing</name> <name>Auditing</name>
<t> <t>
NFSv4.1 provides auditing on a per-file object basis, via the acl NFSv4.1 provides auditing on a per-file object basis, via the acl
and sacl attributes as described in <xref target="acl" format="default"/>. It is and sacl attributes as described in <xref target="acl" format="default"/>. It is
outside the scope of this specification to specify audit log outside the scope of this specification to specify audit log
formats or management policies. formats or management policies.
</t> </t>
</section> </section>
<!-- [auth] Auditing -->
<section anchor="Intrusion_Detection" numbered="true" toc="default"> <section anchor="Intrusion_Detection" numbered="true" toc="default">
<name>Intrusion Detection</name> <name>Intrusion Detection</name>
<t> <t>
NFSv4.1 provides alarm control on a per-file object basis, via the NFSv4.1 provides alarm control on a per-file object basis, via the
acl and sacl attributes as described in <xref target="acl" format="default"/>. acl and sacl attributes as described in <xref target="acl" format="default"/>.
Alarms may serve as the basis for intrusion detection. It is Alarms may serve as the basis for intrusion detection. It is
outside the scope of this specification to specify heuristics for outside the scope of this specification to specify heuristics for
detecting intrusion via alarms. detecting intrusion via alarms.
</t> </t>
</section> </section>
<!-- [auth] Intrusion Detection -->
</section> </section>
<!-- [auth] Non-RPC-based Security Services -->
<section anchor="Transport_Layers" numbered="true" toc="default"> <section anchor="Transport_Layers" numbered="true" toc="default">
<name>Transport Layers</name> <name>Transport Layers</name>
<section anchor="Required_and_Recommended_Transport_Attributes" numbered="true" toc="default"> <section anchor="Required_and_Recommended_Transport_Attributes" numbered="true" toc="default">
<name><bcp14>REQUIRED</bcp14> and <bcp14>RECOMMENDED</bcp14> Properties of Transports</name> <name><bcp14>REQUIRED</bcp14> and <bcp14>RECOMMENDED</bcp14> Properties of Transports</name>
<t> <t>
NFSv4.1 works over Remote Direct Memory Access (RDMA) and non-RDMA-based transports with NFSv4.1 works over Remote Direct Memory Access (RDMA) and non-RDMA-based transports with
the following attributes: the following attributes:
</t> </t>
<ul spacing="normal"> <ul spacing="normal">
skipping to change at line 2265 skipping to change at line 2214
by the connectionless transport is by the connectionless transport is
<bcp14>REQUIRED</bcp14>. As a consequence, UDP by itself <bcp14>MUST NOT</bcp14> be used <bcp14>REQUIRED</bcp14>. As a consequence, UDP by itself <bcp14>MUST NOT</bcp14> be used
as an NFSv4.1 transport. NFSv4.1 assumes that a client transport as an NFSv4.1 transport. NFSv4.1 assumes that a client transport
address and server transport address used to send data address and server transport address used to send data
over a transport together constitute a connection, over a transport together constitute a connection,
even if the underlying transport eschews the concept even if the underlying transport eschews the concept
of a connection. of a connection.
</t> </t>
</section> </section>
<!-- [auth] Required and Recommended Transport Attributes -->
<section anchor="Client_and_Server_Transport_Behavior" numbered="true" toc="default"> <section anchor="Client_and_Server_Transport_Behavior" numbered="true" toc="default">
<name>Client and Server Transport Behavior</name> <name>Client and Server Transport Behavior</name>
<t> <t>
If a connection-oriented transport (e.g., TCP) is used, If a connection-oriented transport (e.g., TCP) is used,
the client and server <bcp14>SHOULD</bcp14> use long-lived connections the client and server <bcp14>SHOULD</bcp14> use long-lived connections
for at least three reasons: for at least three reasons:
</t> </t>
<ol spacing="normal" type="1"> <ol spacing="normal" type="1">
<li> <li>
skipping to change at line 2375 skipping to change at line 2323
sent from it, and credit information appropriate to the channel sent from it, and credit information appropriate to the channel
must be refreshed by the RPC layer. must be refreshed by the RPC layer.
</li> </li>
</ul> </ul>
<t> <t>
In addition, as described in In addition, as described in
<xref target="Retry_and_Replay" format="default"/>, while a session is active, <xref target="Retry_and_Replay" format="default"/>, while a session is active,
the NFSv4.1 requester <bcp14>MUST NOT</bcp14> stop waiting for a reply. the NFSv4.1 requester <bcp14>MUST NOT</bcp14> stop waiting for a reply.
</t> </t>
</section> </section>
<!-- [auth] Client and Server Transport Behavior -->
<section anchor="Ports" numbered="true" toc="default"> <section anchor="Ports" numbered="true" toc="default">
<name>Ports</name> <name>Ports</name>
<t> <t>
Historically, NFSv3 servers have listened over Historically, NFSv3 servers have listened over
TCP port 2049. The registered port 2049 <xref target="RFC3232" format="default"/> TCP port 2049. The registered port 2049 <xref target="RFC3232" format="default"/>
for the NFS protocol should be the default configuration. NFSv4.1 for the NFS protocol should be the default configuration. NFSv4.1
clients <bcp14>SHOULD NOT</bcp14> use the RPC binding protocols as described in clients <bcp14>SHOULD NOT</bcp14> use the RPC binding protocols as described in
<xref target="RFC1833" format="default"/>. <xref target="RFC1833" format="default"/>.
</t> </t>
</section> </section>
<!-- [auth] Ports -->
</section> </section>
<!-- [auth] Transport Layers -->
<section anchor="Session" numbered="true" toc="default"> <section anchor="Session" numbered="true" toc="default">
<name>Session</name> <name>Session</name>
<t> <t>
NFSv4.1 clients and servers <bcp14>MUST</bcp14> support and <bcp14>MUST</bcp14> use the session NFSv4.1 clients and servers <bcp14>MUST</bcp14> support and <bcp14>MUST</bcp14> use the session
feature as described in this section. feature as described in this section.
</t> </t>
<section anchor="Motivation_and_Overview" numbered="true" toc="default"> <section anchor="Motivation_and_Overview" numbered="true" toc="default">
<name>Motivation and Overview</name> <name>Motivation and Overview</name>
skipping to change at line 2486 skipping to change at line 2431
objects as locks, opens, delegations, layouts, etc. are subject to objects as locks, opens, delegations, layouts, etc. are subject to
expiration. The session serves as an object representing a means expiration. The session serves as an object representing a means
of access by a client to the associated client state on the server, of access by a client to the associated client state on the server,
independent of the physical means of access to that state. independent of the physical means of access to that state.
</t> </t>
<t> <t>
A single client may create multiple sessions. A single session <bcp14>MUST A single client may create multiple sessions. A single session <bcp14>MUST
NOT</bcp14> serve multiple clients. NOT</bcp14> serve multiple clients.
</t> </t>
</section> </section>
<!-- [auth] Motivation and Overview -->
<section anchor="NFSv4_Integration" numbered="true" toc="default"> <section anchor="NFSv4_Integration" numbered="true" toc="default">
<name>NFSv4 Integration</name> <name>NFSv4 Integration</name>
<t> <t>
Sessions are part of NFSv4.1 and not NFSv4.0. Normally, a major Sessions are part of NFSv4.1 and not NFSv4.0. Normally, a major
infrastructure change such as sessions would require a new major infrastructure change such as sessions would require a new major
version number to an Open Network Computing (ONC) RPC program like version number to an Open Network Computing (ONC) RPC program like
NFS. However, because NFSv4 encapsulates its functionality in a single procedure, COMPOUND, NFS. However, because NFSv4 encapsulates its functionality in a single procedure, COMPOUND,
and because COMPOUND can support an arbitrary number of and because COMPOUND can support an arbitrary number of
operations, sessions have been added to NFSv4.1 with little difficulty. COMPOUND includes operations, sessions have been added to NFSv4.1 with little difficulty. COMPOUND includes
skipping to change at line 2546 skipping to change at line 2490
COMPOUND, but COMPOUND, but
instead of a SEQUENCE operation, there is a CB_SEQUENCE operation. instead of a SEQUENCE operation, there is a CB_SEQUENCE operation.
CB_COMPOUND also has an additional field called "callback_ident", which CB_COMPOUND also has an additional field called "callback_ident", which
is superfluous in NFSv4.1 and <bcp14>MUST</bcp14> be ignored by is superfluous in NFSv4.1 and <bcp14>MUST</bcp14> be ignored by
the client. CB_SEQUENCE has the same information the client. CB_SEQUENCE has the same information
as SEQUENCE, and also includes other information needed to resolve as SEQUENCE, and also includes other information needed to resolve
callback races callback races
(<xref target="sessions_callback_races" format="default"/>). (<xref target="sessions_callback_races" format="default"/>).
</t> </t>
</section> </section>
<!-- [auth] SEQUENCE and CB_SEQUENCE -->
<section anchor="Client_ID_and_Session_Association" numbered="true" toc="default"> <section anchor="Client_ID_and_Session_Association" numbered="true" toc="default">
<name>Client ID and Session Association</name> <name>Client ID and Session Association</name>
<t> <t>
Each client ID (<xref target="Client_Identifiers" format="default"/>) can have Each client ID (<xref target="Client_Identifiers" format="default"/>) can have
zero or more active sessions. A client ID and associated zero or more active sessions. A client ID and associated
session are required to perform file access in session are required to perform file access in
NFSv4.1. Each time a session is used (whether by a client sending NFSv4.1. Each time a session is used (whether by a client sending
a request to the server or the client replying to a callback a request to the server or the client replying to a callback
request from the server), the state leased to its associated request from the server), the state leased to its associated
skipping to change at line 2578 skipping to change at line 2521
that originally acquired the state pertaining to the that originally acquired the state pertaining to the
callback. For example, if session A is used to callback. For example, if session A is used to
acquire a delegation, a request to recall the acquire a delegation, a request to recall the
delegation <bcp14>MAY</bcp14> arrive over session B if both sessions are delegation <bcp14>MAY</bcp14> arrive over session B if both sessions are
associated with the same client ID. Sections associated with the same client ID. Sections
<xref target="Session_Callback_Security" format="counter"/> and <xref target="Session_Callback_Security" format="counter"/> and
<xref target="Backchannel_RPC_Security" format="counter"/> discuss <xref target="Backchannel_RPC_Security" format="counter"/> discuss
the security considerations around callbacks. the security considerations around callbacks.
</t> </t>
</section> </section>
<!-- [auth] Client ID and Session Association -->
</section> </section>
<!-- [auth] NFSv4 Integration -->
<section anchor="Channels" numbered="true" toc="default"> <section anchor="Channels" numbered="true" toc="default">
<name>Channels</name> <name>Channels</name>
<t> <t>
A channel is not a connection. A channel represents the A channel is not a connection. A channel represents the
direction ONC RPC requests are sent. direction ONC RPC requests are sent.
</t> </t>
<t> <t>
Each session has one or two channels: the fore channel and the backchannel. Each session has one or two channels: the fore channel and the backchannel.
Because there are at most two channels per session, and because each Because there are at most two channels per session, and because each
skipping to change at line 2670 skipping to change at line 2611
</t> </t>
<t> <t>
It is permissible for a connection of one type of It is permissible for a connection of one type of
transport to be associated with the fore channel, transport to be associated with the fore channel,
and a connection of a different type to be associated and a connection of a different type to be associated
with the backchannel. with the backchannel.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] Channels -->
<section anchor="Server_Scope" numbered="true" toc="default"> <section anchor="Server_Scope" numbered="true" toc="default">
<name>Server Scope</name> <name>Server Scope</name>
<t> <t>
Servers each specify a server scope value in the form Servers each specify a server scope value in the form
of an opaque string eir_server_scope returned as part of of an opaque string eir_server_scope returned as part of
the results of an EXCHANGE_ID operation. The purpose of the results of an EXCHANGE_ID operation. The purpose of
the server scope is to allow a group of servers to the server scope is to allow a group of servers to
indicate to clients that a set of servers sharing the indicate to clients that a set of servers sharing the
same server scope value has arranged to use distinct same server scope value has arranged to use distinct
values of opaque identifiers so that the two servers never values of opaque identifiers so that the two servers never
skipping to change at line 3521 skipping to change at line 3461
</section> </section>
<section anchor="err_sequence" numbered="true" toc="default"> <section anchor="err_sequence" numbered="true" toc="default">
<name>Errors from SEQUENCE and CB_SEQUENCE</name> <name>Errors from SEQUENCE and CB_SEQUENCE</name>
<t> <t>
Any time SEQUENCE or CB_SEQUENCE returns an error, the Any time SEQUENCE or CB_SEQUENCE returns an error, the
sequence ID of the slot <bcp14>MUST NOT</bcp14> change. The replier <bcp14>MUST NOT</bcp14> sequence ID of the slot <bcp14>MUST NOT</bcp14> change. The replier <bcp14>MUST NOT</bcp14>
modify the reply cache entry for the slot whenever an error modify the reply cache entry for the slot whenever an error
is returned from SEQUENCE or CB_SEQUENCE. is returned from SEQUENCE or CB_SEQUENCE.
</t> </t>
</section> </section>
<!-- [auth] Errors from SEQUENCE and CB_SEQUENCE -->
<section anchor="optional_reply_caching" numbered="true" toc="default"> <section anchor="optional_reply_caching" numbered="true" toc="default">
<name>Optional Reply Caching</name> <name>Optional Reply Caching</name>
<t> <t>
On a per-request basis, the requester can choose to On a per-request basis, the requester can choose to
direct the replier to cache the reply to all operations direct the replier to cache the reply to all operations
after the first operation (SEQUENCE or CB_SEQUENCE) via after the first operation (SEQUENCE or CB_SEQUENCE) via
the sa_cachethis or csa_cachethis fields of the arguments the sa_cachethis or csa_cachethis fields of the arguments
to SEQUENCE or CB_SEQUENCE. to SEQUENCE or CB_SEQUENCE.
The reason it would not direct the replier to cache The reason it would not direct the replier to cache
the entire reply is that the request is composed of all the entire reply is that the request is composed of all
skipping to change at line 3631 skipping to change at line 3570
client any of the following responses: client any of the following responses:
</t> </t>
<ul spacing="normal"> <ul spacing="normal">
<li> <li>
The cached reply to the original request (if the replier has cached The cached reply to the original request (if the replier has cached
it in its entirety and the users of the original request and retry match). it in its entirety and the users of the original request and retry match).
</li> </li>
<li> <li>
A reply that consists only of the Sequence operation with the error A reply that consists only of the Sequence operation with the error
NFS4ERR_FALSE_RETRY. NFS4ERR_SEQ_FALSE_RETRY.
</li> </li>
<li> <li>
A reply consisting of the response to Sequence with the status A reply consisting of the response to Sequence with the status
NFS4_OK, together with the second operation as it appeared in the retried NFS4_OK, together with the second operation as it appeared in the retried
request with an error of NFS4ERR_RETRY_UNCACHED_REP or other error as request with an error of NFS4ERR_RETRY_UNCACHED_REP or other error as
described above. described above.
</li> </li>
<li> <li>
A reply that consists of the response to Sequence with the status A reply that consists of the response to Sequence with the status
NFS4_OK, together with the second operation as it appeared in the original NFS4_OK, together with the second operation as it appeared in the original
skipping to change at line 3663 skipping to change at line 3602
the same as the original request, the same as the original request,
including a retry that has different including a retry that has different
operations or different arguments in the operations or different arguments in the
operations from the original and a retry operations from the original and a retry
that uses a different principal in the that uses a different principal in the
RPC request's credential field that RPC request's credential field that
translates to a different user, then this translates to a different user, then this
is a false retry. When the replier is a false retry. When the replier
detects a false retry, it is permitted detects a false retry, it is permitted
(but not always obligated) to return (but not always obligated) to return
NFS4ERR_FALSE_RETRY in response to the NFS4ERR_SEQ_FALSE_RETRY in response to the
Sequence operation when it detects a Sequence operation when it detects a
false retry. false retry.
</t> </t>
<t> <t>
Translations of particularly privileged Translations of particularly privileged
user values to other users due to the user values to other users due to the
lack of appropriately secure credentials, lack of appropriately secure credentials,
as configured on the replier, should be as configured on the replier, should be
applied before determining whether the applied before determining whether the
users are the same or different. If the users are the same or different. If the
replier determines the users are replier determines the users are
different between the original request different between the original request
and a retry, then the replier <bcp14>MUST</bcp14> return and a retry, then the replier <bcp14>MUST</bcp14> return
NFS4ERR_FALSE_RETRY. NFS4ERR_SEQ_FALSE_RETRY.
</t> </t>
<t> <t>
If an operation of the retry is an If an operation of the retry is an
illegal operation, or an operation that illegal operation, or an operation that
was legal in a previous minor version of was legal in a previous minor version of
NFSv4 and <bcp14>MUST NOT</bcp14> be supported in the NFSv4 and <bcp14>MUST NOT</bcp14> be supported in the
current minor version (e.g., SETCLIENTID), current minor version (e.g., SETCLIENTID),
the replier <bcp14>MAY</bcp14> return the replier <bcp14>MAY</bcp14> return
NFS4ERR_FALSE_RETRY (and <bcp14>MUST</bcp14> do so if NFS4ERR_SEQ_FALSE_RETRY (and <bcp14>MUST</bcp14> do so if
the users of the original request and the users of the original request and
retry differ). Otherwise, the replier <bcp14>MAY</bcp14> return retry differ). Otherwise, the replier <bcp14>MAY</bcp14> return
NFS4ERR_OP_ILLEGAL or NFS4ERR_BADXDR or NFS4ERR_OP_ILLEGAL or NFS4ERR_BADXDR or
NFS4ERR_NOTSUPP as appropriate. Note NFS4ERR_NOTSUPP as appropriate. Note
that the handling is in contrast for how the that the handling is in contrast for how the
replier deals with retries requests with replier deals with retries requests with
no cached reply. The difference is due to no cached reply. The difference is due to
NFS4ERR_FALSE_RETRY being a valid error NFS4ERR_SEQ_FALSE_RETRY being a valid error
for only Sequence operations, whereas for only Sequence operations, whereas
NFS4ERR_RETRY_UNCACHED_REP is a valid NFS4ERR_RETRY_UNCACHED_REP is a valid
error for all operations except illegal error for all operations except illegal
operations and operations that <bcp14>MUST NOT</bcp14> be operations and operations that <bcp14>MUST NOT</bcp14> be
supported in the current minor version of supported in the current minor version of
NFSv4. NFSv4.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] Optional Reply Caching -->
</section> </section>
<!-- [auth] Slot Identifiers and Server Reply Cache -->
<section anchor="Retry_and_Replay" numbered="true" toc="default"> <section anchor="Retry_and_Replay" numbered="true" toc="default">
<name>Retry and Replay of Reply</name> <name>Retry and Replay of Reply</name>
<t> <t>
A requester <bcp14>MUST NOT</bcp14> retry a request, unless A requester <bcp14>MUST NOT</bcp14> retry a request, unless
the connection it used to send the request the connection it used to send the request
disconnects. The requester can then reconnect disconnects. The requester can then reconnect
and re-send the request, or it can re-send the and re-send the request, or it can re-send the
request over a different connection that is request over a different connection that is
associated with the same session. associated with the same session.
skipping to change at line 3780 skipping to change at line 3717
progress on the replier. The replier <bcp14>SHOULD</bcp14> deal with the issue progress on the replier. The replier <bcp14>SHOULD</bcp14> deal with the issue
by returning NFS4ERR_DELAY as the reply to SEQUENCE or CB_SEQUENCE by returning NFS4ERR_DELAY as the reply to SEQUENCE or CB_SEQUENCE
operation, but implementations <bcp14>MAY</bcp14> return NFS4ERR_MISORDERED. operation, but implementations <bcp14>MAY</bcp14> return NFS4ERR_MISORDERED.
Since errors from SEQUENCE and CB_SEQUENCE are Since errors from SEQUENCE and CB_SEQUENCE are
never recorded in the reply cache, this approach allows the never recorded in the reply cache, this approach allows the
results of the execution of the original request to be results of the execution of the original request to be
properly recorded in the reply cache (assuming that the requester properly recorded in the reply cache (assuming that the requester
specified the reply to be cached). specified the reply to be cached).
</t> </t>
</section> </section>
<!-- [auth] Retry and Replay -->
<section anchor="sessions_callback_races" numbered="true" toc="default"> <section anchor="sessions_callback_races" numbered="true" toc="default">
<name>Resolving Server Callback Races</name> <name>Resolving Server Callback Races</name>
<t> <t>
It is possible for server callbacks to arrive at the It is possible for server callbacks to arrive at the
client before the reply from related fore channel client before the reply from related fore channel
operations. For example, a client may have been operations. For example, a client may have been
granted a delegation to a file it has opened, but the granted a delegation to a file it has opened, but the
reply to the OPEN (informing the client of the reply to the OPEN (informing the client of the
granting of the delegation) may be delayed in the granting of the delegation) may be delayed in the
skipping to change at line 3860 skipping to change at line 3796
the average round-trip time for COMPOUND requests to the the average round-trip time for COMPOUND requests to the
server, and wait that period of time. If server, and wait that period of time. If
that period of time that period of time
expires, it can respond to the CB_COMPOUND with expires, it can respond to the CB_COMPOUND with
NFS4ERR_DELAY. There are other scenarios under which callbacks NFS4ERR_DELAY. There are other scenarios under which callbacks
may race replies. may race replies.
Among them are pNFS layout recalls as described in Among them are pNFS layout recalls as described in
<xref target="pnfs_operation_sequencing" format="default"/>. <xref target="pnfs_operation_sequencing" format="default"/>.
</t> </t>
</section> </section>
<!-- [auth] Resolving server callback races with sessions -->
<section anchor="COMPOUND_Sizing_Issues" numbered="true" toc="default"> <section anchor="COMPOUND_Sizing_Issues" numbered="true" toc="default">
<name>COMPOUND and CB_COMPOUND Construction Issues</name> <name>COMPOUND and CB_COMPOUND Construction Issues</name>
<t> <t>
Very large requests and replies may pose both buffer Very large requests and replies may pose both buffer
management issues (especially with RDMA) and reply management issues (especially with RDMA) and reply
cache issues. When the session is created cache issues. When the session is created
(<xref target="OP_CREATE_SESSION" format="default"/>), for each channel (fore and (<xref target="OP_CREATE_SESSION" format="default"/>), for each channel (fore and
back), the client and server back), the client and server
negotiate the maximum-sized request they will negotiate the maximum-sized request they will
send or process (ca_maxrequestsize), the maximum-sized reply send or process (ca_maxrequestsize), the maximum-sized reply
skipping to change at line 3980 skipping to change at line 3915
A server <bcp14>MAY</bcp14> return NFS4ERR_UNSAFE_COMPOUND to a non-idempotent A server <bcp14>MAY</bcp14> return NFS4ERR_UNSAFE_COMPOUND to a non-idempotent
current filehandle-changing operation, if current filehandle-changing operation, if
it looks at the next operation (in the same COMPOUND procedure) it looks at the next operation (in the same COMPOUND procedure)
and finds it is and finds it is
not GETFH. The server <bcp14>SHOULD</bcp14> do this if it is unable to not GETFH. The server <bcp14>SHOULD</bcp14> do this if it is unable to
determine in advance whether the total response size determine in advance whether the total response size
would exceed ca_maxresponsesize_cached or ca_maxresponsesize. would exceed ca_maxresponsesize_cached or ca_maxresponsesize.
</li> </li>
</ul> </ul>
</section> </section>
<!-- [auth] COMPOUND and CB_COMPOUND Construction Issues -->
<section anchor="Persistence" numbered="true" toc="default"> <section anchor="Persistence" numbered="true" toc="default">
<name>Persistence</name> <name>Persistence</name>
<t> <t>
Since the reply cache is bounded, it is practical for Since the reply cache is bounded, it is practical for
the reply cache to persist across server restarts. the reply cache to persist across server restarts.
The replier <bcp14>MUST</bcp14> persist the following information The replier <bcp14>MUST</bcp14> persist the following information
if it agreed to persist the session (when the session if it agreed to persist the session (when the session
was created; see <xref target="OP_CREATE_SESSION" format="default"/>): was created; see <xref target="OP_CREATE_SESSION" format="default"/>):
</t> </t>
skipping to change at line 4085 skipping to change at line 4019
before starting the NFSv4.1 server. before starting the NFSv4.1 server.
</t> </t>
<t> <t>
While the description of the While the description of the
implementation for atomic execution of the request implementation for atomic execution of the request
and caching of the reply and caching of the reply
is beyond the scope of this document, an example implementation is beyond the scope of this document, an example implementation
for NFSv2 <xref target="RFC1094" format="default"/> is described in <xref target="ha_nfs_ibm" format="default"/>. for NFSv2 <xref target="RFC1094" format="default"/> is described in <xref target="ha_nfs_ibm" format="default"/>.
</t> </t>
</section> </section>
<!-- [auth] Persistence -->
</section> </section>
<!-- [auth] Exactly Once Semantics -->
<section anchor="RDMA_Considerations" numbered="true" toc="default"> <section anchor="RDMA_Considerations" numbered="true" toc="default">
<name>RDMA Considerations</name> <name>RDMA Considerations</name>
<t> <t>
A complete discussion of the operation of RPC-based A complete discussion of the operation of RPC-based
protocols over RDMA transports is in <xref target="RFC8166" format="default"/>. A protocols over RDMA transports is in <xref target="RFC8166" format="default"/>. A
discussion of the operation of NFSv4, including NFSv4.1, discussion of the operation of NFSv4, including NFSv4.1,
over RDMA is in <xref target="RFC8267" format="default"/>. Where RDMA is considered, over RDMA is in <xref target="RFC8267" format="default"/>. Where RDMA is considered,
this specification assumes the use of such a layering; this specification assumes the use of such a layering;
it addresses only the upper-layer issues relevant to it addresses only the upper-layer issues relevant to
making best use of RPC/RDMA. making best use of RPC/RDMA.
skipping to change at line 4139 skipping to change at line 4071
RDMA to a remote buffer, it has to have both an NFSv4.1 RDMA to a remote buffer, it has to have both an NFSv4.1
slot and an RDMA credit. If multiple RDMA connections slot and an RDMA credit. If multiple RDMA connections
are associated with a session, then if the total number are associated with a session, then if the total number
of credits across all RDMA connections associated with of credits across all RDMA connections associated with
the session is X, and the number of slots in the session the session is X, and the number of slots in the session
is Y, then the maximum number of outstanding requests is Y, then the maximum number of outstanding requests
is the lesser of X and Y. is the lesser of X and Y.
</t> </t>
</section> </section>
<!-- [auth] RDMA Connection Resources -->
<section anchor="Flow_Control" numbered="true" toc="default"> <section anchor="Flow_Control" numbered="true" toc="default">
<name>Flow Control</name> <name>Flow Control</name>
<t> <t>
Previous versions of NFS do not provide flow control; Previous versions of NFS do not provide flow control;
instead, they rely on the windowing provided by instead, they rely on the windowing provided by
transports like TCP to throttle requests. This does transports like TCP to throttle requests. This does
not work with RDMA, which provides no operation flow not work with RDMA, which provides no operation flow
control and will terminate a connection in error when control and will terminate a connection in error when
limits are exceeded. limits are exceeded.
skipping to change at line 4178 skipping to change at line 4109
dynamically at the replier's choosing by manipulating dynamically at the replier's choosing by manipulating
certain parameters present in each NFSv4.1 reply. In certain parameters present in each NFSv4.1 reply. In
addition, the CB_RECALL_SLOT callback operation (see addition, the CB_RECALL_SLOT callback operation (see
<xref target="OP_CB_RECALL_SLOT" format="default"/>) can be sent by <xref target="OP_CB_RECALL_SLOT" format="default"/>) can be sent by
a server to a client to return RDMA credits to the a server to a client to return RDMA credits to the
server, thereby lowering the maximum number of requests server, thereby lowering the maximum number of requests
a client can have outstanding to the server. a client can have outstanding to the server.
</t> </t>
</section> </section>
<!-- [auth] Flow Control -->
<section anchor="Padding" numbered="true" toc="default"> <section anchor="Padding" numbered="true" toc="default">
<name>Padding</name> <name>Padding</name>
<t> <t>
Header padding is requested by each peer at session initiation Header padding is requested by each peer at session initiation
(see the ca_headerpadsize argument to CREATE_SESSION in (see the ca_headerpadsize argument to CREATE_SESSION in
<xref target="OP_CREATE_SESSION" format="default"/>), and <xref target="OP_CREATE_SESSION" format="default"/>), and
subsequently used by the RPC RDMA layer, as described in <xref target="RFC8166" format="default"/>. subsequently used by the RPC RDMA layer, as described in <xref target="RFC8166" format="default"/>.
Zero padding is permitted. Zero padding is permitted.
</t> </t>
skipping to change at line 4244 skipping to change at line 4174
next posted receive if unused by the actual received request, or next posted receive if unused by the actual received request, or
may pass the now-complete buffers by reference for normal write may pass the now-complete buffers by reference for normal write
processing. For a server that can make use of it, this removes processing. For a server that can make use of it, this removes
any need for data copies of incoming data, without resorting to any need for data copies of incoming data, without resorting to
complicated end-to-end buffer advertisement and management. This complicated end-to-end buffer advertisement and management. This
includes most kernel-based and integrated server designs, among includes most kernel-based and integrated server designs, among
many others. The client may perform similar optimizations, if many others. The client may perform similar optimizations, if
desired. desired.
</t> </t>
</section> </section>
<!-- [auth] Padding -->
<section anchor="dual" numbered="true" toc="default"> <section anchor="dual" numbered="true" toc="default">
<name>Dual RDMA and Non-RDMA Transports</name> <name>Dual RDMA and Non-RDMA Transports</name>
<t> <t>
Some RDMA transports (e.g., RFC 5040 <xref target="RFC5040" format="default"/>) Some RDMA transports (e.g., RFC 5040 <xref target="RFC5040" format="default"/>)
permit a "streaming" (non-RDMA) phase, permit a "streaming" (non-RDMA) phase,
where ordinary traffic might flow before "stepping up" where ordinary traffic might flow before "stepping up"
to RDMA mode, commencing RDMA traffic. Some RDMA to RDMA mode, commencing RDMA traffic. Some RDMA
transports start connections always in RDMA mode. transports start connections always in RDMA mode.
NFSv4.1 allows, but does not assume, a streaming phase NFSv4.1 allows, but does not assume, a streaming phase
before RDMA mode. When a connection before RDMA mode. When a connection
is associated with a session, the client and server negotiate whether the is associated with a session, the client and server negotiate whether the
connection is used in RDMA or non-RDMA mode (see Sections connection is used in RDMA or non-RDMA mode (see Sections
<xref target="OP_CREATE_SESSION" format="counter"/> and <xref target="OP_CREATE_SESSION" format="counter"/> and
<xref target="OP_BIND_CONN_TO_SESSION" format="counter"/>). <xref target="OP_BIND_CONN_TO_SESSION" format="counter"/>).
</t> </t>
</section> </section>
<!-- [auth] RDMA Transports -->
</section> </section>
<!-- [auth] RDMA Considerations -->
<section anchor="Sessions_Security" numbered="true" toc="default"> <section anchor="Sessions_Security" numbered="true" toc="default">
<name>Session Security</name> <name>Session Security</name>
<section anchor="Session_Callback_Security" numbered="true" toc="default"> <section anchor="Session_Callback_Security" numbered="true" toc="default">
<name>Session Callback Security</name> <name>Session Callback Security</name>
<t> <t>
Via session/connection association, NFSv4.1 improves security over Via session/connection association, NFSv4.1 improves security over
that provided by NFSv4.0 for the backchannel. The that provided by NFSv4.0 for the backchannel. The
connection is client-initiated (see connection is client-initiated (see
<xref target="OP_BIND_CONN_TO_SESSION" format="default"/>) and subject to the same <xref target="OP_BIND_CONN_TO_SESSION" format="default"/>) and subject to the same
firewall and routing checks as the fore channel. firewall and routing checks as the fore channel.
At the client's option (see <xref target="OP_EXCHANGE_ID" format="default"/>), At the client's option (see <xref target="OP_EXCHANGE_ID" format="default"/>),
connection association is fully authenticated before being connection association is fully authenticated before being
activated (see <xref target="OP_BIND_CONN_TO_SESSION" format="default"/>). activated (see <xref target="OP_BIND_CONN_TO_SESSION" format="default"/>).
Traffic from the server over the Traffic from the server over the
backchannel is authenticated exactly as the client specifies backchannel is authenticated exactly as the client specifies
(see <xref target="Backchannel_RPC_Security" format="default"/>). (see <xref target="Backchannel_RPC_Security" format="default"/>).
</t> </t>
</section> </section>
<!-- [auth] Session Callback Security -->
<section anchor="Backchannel_RPC_Security" numbered="true" toc="default"> <section anchor="Backchannel_RPC_Security" numbered="true" toc="default">
<name>Backchannel RPC Security</name> <name>Backchannel RPC Security</name>
<t> <t>
When the NFSv4.1 client establishes the backchannel, it When the NFSv4.1 client establishes the backchannel, it
informs the server of the security flavors and principals informs the server of the security flavors and principals
to use when sending requests. If the security flavor is to use when sending requests. If the security flavor is
RPCSEC_GSS, the client expresses the principal in the form RPCSEC_GSS, the client expresses the principal in the form
of an established RPCSEC_GSS context. The server is free of an established RPCSEC_GSS context. The server is free
to use any of the flavor/principal combinations the client to use any of the flavor/principal combinations the client
offers, but it <bcp14>MUST NOT</bcp14> use unoffered combinations. offers, but it <bcp14>MUST NOT</bcp14> use unoffered combinations.
skipping to change at line 4313 skipping to change at line 4239
The CREATE_SESSION (<xref target="OP_CREATE_SESSION" format="default"/>) The CREATE_SESSION (<xref target="OP_CREATE_SESSION" format="default"/>)
and BACKCHANNEL_CTL (<xref target="OP_BACKCHANNEL_CTL" format="default"/>) and BACKCHANNEL_CTL (<xref target="OP_BACKCHANNEL_CTL" format="default"/>)
operations allow the client to specify flavor/principal combinations. operations allow the client to specify flavor/principal combinations.
</t> </t>
<t> <t>
Also note that the SP4_SSV state protection mode Also note that the SP4_SSV state protection mode
(see Sections <xref target="OP_EXCHANGE_ID" format="counter"/> and <xref target="protect_state_change" format="counter"/>) has the side (see Sections <xref target="OP_EXCHANGE_ID" format="counter"/> and <xref target="protect_state_change" format="counter"/>) has the side
benefit of providing SSV-derived RPCSEC_GSS contexts (<xref target="ssv_mech" format="default"/>). benefit of providing SSV-derived RPCSEC_GSS contexts (<xref target="ssv_mech" format="default"/>).
</t> </t>
</section> </section>
<!-- [auth] Backchannel RPC Security -->
<section anchor="protect_state_change" numbered="true" toc="default"> <section anchor="protect_state_change" numbered="true" toc="default">
<name>Protection from Unauthorized State Changes</name> <name>Protection from Unauthorized State Changes</name>
<t> <t>
As described to this point in the specification, the state model As described to this point in the specification, the state model
of NFSv4.1 is vulnerable to an attacker that of NFSv4.1 is vulnerable to an attacker that
sends a SEQUENCE operation with a forged session ID and with a slot ID that sends a SEQUENCE operation with a forged session ID and with a slot ID that
it expects the legitimate client to use next. When the legitimate client it expects the legitimate client to use next. When the legitimate client
uses the slot ID with the same sequence number, the server uses the slot ID with the same sequence number, the server
returns the attacker's result from the reply cache, which returns the attacker's result from the reply cache, which
skipping to change at line 4631 skipping to change at line 4556
<t> <t>
If a connection hijack occurs, the hijacker could in If a connection hijack occurs, the hijacker could in
theory change locking state and negatively impact the theory change locking state and negatively impact the
service to legitimate clients. However, if the server service to legitimate clients. However, if the server
is configured to require the use of RPCSEC_GSS with is configured to require the use of RPCSEC_GSS with
integrity or privacy on the affected file objects, and integrity or privacy on the affected file objects, and
if EXCHGID4_FLAG_BIND_PRINC_STATEID capability (<xref target="OP_EXCHANGE_ID" format="default"/>) is in force, this will if EXCHGID4_FLAG_BIND_PRINC_STATEID capability (<xref target="OP_EXCHANGE_ID" format="default"/>) is in force, this will
thwart unauthorized attempts to change locking state. thwart unauthorized attempts to change locking state.
</t> </t>
</section> </section>
<!-- [auth] Protection from Unauthorized State Changes -->
</section> </section>
<!-- [auth] Sessions Security -->
<section anchor="ssv_mech" numbered="true" toc="default"> <section anchor="ssv_mech" numbered="true" toc="default">
<name>The Secret State Verifier (SSV) GSS Mechanism</name> <name>The Secret State Verifier (SSV) GSS Mechanism</name>
<t> <t>
The SSV provides the secret key for a GSS mechanism internal to NFSv4.1 The SSV provides the secret key for a GSS mechanism internal to NFSv4.1
that NFSv4.1 uses for state protection. Contexts for this that NFSv4.1 uses for state protection. Contexts for this
mechanism are not established via the RPCSEC_GSS mechanism are not established via the RPCSEC_GSS
protocol. Instead, the contexts are automatically protocol. Instead, the contexts are automatically
created when EXCHANGE_ID specifies created when EXCHANGE_ID specifies
SP4_SSV protection. The only tokens SP4_SSV protection. The only tokens
defined are the PerMsgToken (emitted by GSS_GetMIC) defined are the PerMsgToken (emitted by GSS_GetMIC)
skipping to change at line 4679 skipping to change at line 4602
enumeration value for that subkey of data type ssv_subkey4. enumeration value for that subkey of data type ssv_subkey4.
If the length of the output of the HMAC algorithm exceeds the length of If the length of the output of the HMAC algorithm exceeds the length of
key of the encryption algorithm (which is also negotiated by EXCHANGE_ID), key of the encryption algorithm (which is also negotiated by EXCHANGE_ID),
then the subkey <bcp14>MUST</bcp14> be truncated from the HMAC output, i.e., if the then the subkey <bcp14>MUST</bcp14> be truncated from the HMAC output, i.e., if the
subkey is of N bytes long, then the first N bytes of the HMAC output subkey is of N bytes long, then the first N bytes of the HMAC output
<bcp14>MUST</bcp14> be used for the subkey. The specification of EXCHANGE_ID <bcp14>MUST</bcp14> be used for the subkey. The specification of EXCHANGE_ID
states that the length of the output of the HMAC algorithm <bcp14>MUST NOT</bcp14> states that the length of the output of the HMAC algorithm <bcp14>MUST NOT</bcp14>
be less than the length of subkey needed for the encryption algorithm be less than the length of subkey needed for the encryption algorithm
(see <xref target="OP_EXCHANGE_ID" format="default"/>). (see <xref target="OP_EXCHANGE_ID" format="default"/>).
</t> </t>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
/* Input for computing subkeys */ /* Input for computing subkeys */
enum ssv_subkey4 { enum ssv_subkey4 {
SSV4_SUBKEY_MIC_I2T = 1, SSV4_SUBKEY_MIC_I2T = 1,
SSV4_SUBKEY_MIC_T2I = 2, SSV4_SUBKEY_MIC_T2I = 2,
SSV4_SUBKEY_SEAL_I2T = 3, SSV4_SUBKEY_SEAL_I2T = 3,
SSV4_SUBKEY_SEAL_T2I = 4 SSV4_SUBKEY_SEAL_T2I = 4
}; };
]]></sourcecode> ]]></sourcecode>
<t> <t>
The subkey derived from SSV4_SUBKEY_MIC_I2T The subkey derived from SSV4_SUBKEY_MIC_I2T
skipping to change at line 4704 skipping to change at line 4627
SSV4_SUBKEY_MIC_T2I is used for MICs originating from the SSV4_SUBKEY_MIC_T2I is used for MICs originating from the
NFSv4.1 server. The subkey derived from SSV4_SUBKEY_SEAL_I2T NFSv4.1 server. The subkey derived from SSV4_SUBKEY_SEAL_I2T
is used for encryption text originating from the NFSv4.1 is used for encryption text originating from the NFSv4.1
client, and the subkey derived from SSV4_SUBKEY_SEAL_T2I client, and the subkey derived from SSV4_SUBKEY_SEAL_T2I
is used for encryption text originating from the is used for encryption text originating from the
NFSv4.1 server. NFSv4.1 server.
</t> </t>
<t> <t>
The PerMsgToken description is based on an XDR definition: The PerMsgToken description is based on an XDR definition:
</t> </t>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
/* Input for computing smt_hmac */ /* Input for computing smt_hmac */
struct ssv_mic_plain_tkn4 { struct ssv_mic_plain_tkn4 {
uint32_t smpt_ssv_seq; uint32_t smpt_ssv_seq;
opaque smpt_orig_plain<>; opaque smpt_orig_plain<>;
}; };
]]></sourcecode> ]]></sourcecode>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
/* SSV GSS PerMsgToken token */ /* SSV GSS PerMsgToken token */
struct ssv_mic_tkn4 { struct ssv_mic_tkn4 {
uint32_t smt_ssv_seq; uint32_t smt_ssv_seq;
opaque smt_hmac<>; opaque smt_hmac<>;
}; };
]]></sourcecode> ]]></sourcecode>
<t> <t>
The field smt_hmac is an HMAC calculated by using the The field smt_hmac is an HMAC calculated by using the
subkey derived from SSV4_SUBKEY_MIC_I2T or subkey derived from SSV4_SUBKEY_MIC_I2T or
skipping to change at line 4759 skipping to change at line 4682
operations. operations.
Once the HMAC is calculated, it is XDR encoded into Once the HMAC is calculated, it is XDR encoded into
smt_hmac, which will include an initial four-byte length, smt_hmac, which will include an initial four-byte length,
and any necessary padding. Prepended to this will be and any necessary padding. Prepended to this will be
the XDR encoded value of smt_ssv_seq. the XDR encoded value of smt_ssv_seq.
</t> </t>
<t> <t>
The SealedMessage description is based on an XDR definition: The SealedMessage description is based on an XDR definition:
</t> </t>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
/* Input for computing ssct_encr_data and ssct_hmac */ /* Input for computing ssct_encr_data and ssct_hmac */
struct ssv_seal_plain_tkn4 { struct ssv_seal_plain_tkn4 {
opaque sspt_confounder<>; opaque sspt_confounder<>;
uint32_t sspt_ssv_seq; uint32_t sspt_ssv_seq;
opaque sspt_orig_plain<>; opaque sspt_orig_plain<>;
opaque sspt_pad<>; opaque sspt_pad<>;
}; };
]]></sourcecode> ]]></sourcecode>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
/* SSV GSS SealedMessage token */ /* SSV GSS SealedMessage token */
struct ssv_seal_cipher_tkn4 { struct ssv_seal_cipher_tkn4 {
uint32_t ssct_ssv_seq; uint32_t ssct_ssv_seq;
opaque ssct_iv<>; opaque ssct_iv<>;
opaque ssct_encr_data<>; opaque ssct_encr_data<>;
opaque ssct_hmac<>; opaque ssct_hmac<>;
}; };
]]></sourcecode> ]]></sourcecode>
<t> <t>
The token emitted by GSS_Wrap() is XDR encoded and The token emitted by GSS_Wrap() is XDR encoded and
skipping to change at line 4919 skipping to change at line 4842
</t> </t>
<t> <t>
The SSV mechanism does not support replay detection and sequencing The SSV mechanism does not support replay detection and sequencing
in its tokens because RPCSEC_GSS does not use those features (see in its tokens because RPCSEC_GSS does not use those features (see
"Context Creation Requests", <xref target="RFC2203" sectionFormat="of" section="5.2.2"/>). However, <xref target="rpcsec_ssv_consider" format="default"/> discusses special "Context Creation Requests", <xref target="RFC2203" sectionFormat="of" section="5.2.2"/>). However, <xref target="rpcsec_ssv_consider" format="default"/> discusses special
considerations for the SSV mechanism when used with RPCSEC_GSS. considerations for the SSV mechanism when used with RPCSEC_GSS.
</t> </t>
</section> </section>
<!-- [auth] The SSV GSS Mechanism -->
<section anchor="rpcsec_ssv_consider" numbered="true" toc="default"> <section anchor="rpcsec_ssv_consider" numbered="true" toc="default">
<name>Security Considerations for RPCSEC_GSS When Using the SSV Mechanism</name> <name>Security Considerations for RPCSEC_GSS When Using the SSV Mechanism</name>
<t> <t>
When a client ID is created with SP4_SSV state protection (see <xref target="OP_EXCHANGE_ID" format="default"/>), the client is permitted to associate When a client ID is created with SP4_SSV state protection (see <xref target="OP_EXCHANGE_ID" format="default"/>), the client is permitted to associate
multiple RPCSEC_GSS handles with the single SSV GSS context multiple RPCSEC_GSS handles with the single SSV GSS context
(see <xref target="ssv_mech" format="default"/>). Because of the way RPCSEC_GSS (see <xref target="ssv_mech" format="default"/>). Because of the way RPCSEC_GSS
(both version 1 and version 2, see <xref target="RFC2203" format="default"/> and (both version 1 and version 2, see <xref target="RFC2203" format="default"/> and
<xref target="RFC5403" format="default"/>) calculate the verifier of the reply, <xref target="RFC5403" format="default"/>) calculate the verifier of the reply,
special care must be taken by the implementation of the NFSv4.1 special care must be taken by the implementation of the NFSv4.1
skipping to change at line 5003 skipping to change at line 4925
<section anchor="Obligations_of_the_Server" numbered="true" toc="default"> <section anchor="Obligations_of_the_Server" numbered="true" toc="default">
<name>Obligations of the Server</name> <name>Obligations of the Server</name>
<t> <t>
The server has the primary obligation to monitor the The server has the primary obligation to monitor the
state of backchannel resources that the client has state of backchannel resources that the client has
created for the server (RPCSEC_GSS contexts and backchannel created for the server (RPCSEC_GSS contexts and backchannel
connections). If these resources vanish, the connections). If these resources vanish, the
server takes action as specified in <xref target="Events_Requiring_Server_Action" format="default"/>. server takes action as specified in <xref target="Events_Requiring_Server_Action" format="default"/>.
</t> </t>
</section> </section>
<!-- [auth] Obligations of the Server -->
<section anchor="Obligations_of_the_Client" numbered="true" toc="default"> <section anchor="Obligations_of_the_Client" numbered="true" toc="default">
<name>Obligations of the Client</name> <name>Obligations of the Client</name>
<t> <t>
The client <bcp14>SHOULD</bcp14> honor the following obligations in order to The client <bcp14>SHOULD</bcp14> honor the following obligations in order to
utilize the session: utilize the session:
</t> </t>
<ul spacing="normal"> <ul spacing="normal">
<li> <li>
Keep a necessary session from going idle on the server. A client Keep a necessary session from going idle on the server. A client
skipping to change at line 5055 skipping to change at line 4976
restarted without sending a disconnect). The onus is restarted without sending a disconnect). The onus is
on the server, not the client, to determine if the on the server, not the client, to determine if the
backchannel's connection is alive, and to indicate in backchannel's connection is alive, and to indicate in
the response to a SEQUENCE operation when the last the response to a SEQUENCE operation when the last
connection associated with a session's backchannel connection associated with a session's backchannel
has disconnected. has disconnected.
</li> </li>
</ul> </ul>
</section> </section>
<!-- [auth] Obligations of the Client -->
<section anchor="Steps_the_Client_Takes_To_Establish_a_Session" numbered="true" toc="default"> <section anchor="Steps_the_Client_Takes_To_Establish_a_Session" numbered="true" toc="default">
<name>Steps the Client Takes to Establish a Session</name> <name>Steps the Client Takes to Establish a Session</name>
<t> <t>
If the client does not have a client ID, the client If the client does not have a client ID, the client
sends EXCHANGE_ID to establish a client ID. If it sends EXCHANGE_ID to establish a client ID. If it
opts for SP4_MACH_CRED or SP4_SSV protection, in the opts for SP4_MACH_CRED or SP4_SSV protection, in the
spo_must_enforce list of operations, it <bcp14>SHOULD</bcp14> at spo_must_enforce list of operations, it <bcp14>SHOULD</bcp14> at
minimum specify CREATE_SESSION, DESTROY_SESSION, minimum specify CREATE_SESSION, DESTROY_SESSION,
BIND_CONN_TO_SESSION, BACKCHANNEL_CTL, and DESTROY_CLIENTID. BIND_CONN_TO_SESSION, BACKCHANNEL_CTL, and DESTROY_CLIENTID.
skipping to change at line 5119 skipping to change at line 5039
additional connections for the fore channel, then additional connections for the fore channel, then
it needs to call BIND_CONN_TO_SESSION if it specified it needs to call BIND_CONN_TO_SESSION if it specified
SP4_SSV or SP4_MACH_CRED state protection when the SP4_SSV or SP4_MACH_CRED state protection when the
client ID was created. client ID was created.
</t> </t>
<t> <t>
At this point, the session has reached steady state. At this point, the session has reached steady state.
</t> </t>
</section> </section>
<!-- [auth] Steps the Client Takes To Establish a Session -->
</section> </section>
<!-- [auth] Session Mechanics - Steady State -->
<section anchor="session_inactive" numbered="true" toc="default"> <section anchor="session_inactive" numbered="true" toc="default">
<name>Session Inactivity Timer</name> <name>Session Inactivity Timer</name>
<t> <t>
The server <bcp14>MAY</bcp14> maintain a session inactivity timer for The server <bcp14>MAY</bcp14> maintain a session inactivity timer for
each session. If the session inactivity timer expires, each session. If the session inactivity timer expires,
then the server <bcp14>MAY</bcp14> destroy the session. To avoid losing then the server <bcp14>MAY</bcp14> destroy the session. To avoid losing
a session due to inactivity, the client <bcp14>MUST</bcp14> renew a session due to inactivity, the client <bcp14>MUST</bcp14> renew
the session inactivity timer. The length of session the session inactivity timer. The length of session
inactivity timer <bcp14>MUST NOT</bcp14> be less than the lease_time inactivity timer <bcp14>MUST NOT</bcp14> be less than the lease_time
skipping to change at line 5161 skipping to change at line 5079
<name>RPCSEC_GSS Context Loss by Callback Path</name> <name>RPCSEC_GSS Context Loss by Callback Path</name>
<t> <t>
If all RPCSEC_GSS handles If all RPCSEC_GSS handles
granted by the client to the server for callback use have granted by the client to the server for callback use have
expired, the client <bcp14>MUST</bcp14> expired, the client <bcp14>MUST</bcp14>
establish a new handle via BACKCHANNEL_CTL. The establish a new handle via BACKCHANNEL_CTL. The
sr_status_flags field of the SEQUENCE results indicates when callback handles sr_status_flags field of the SEQUENCE results indicates when callback handles
are nearly expired, or fully expired (see <xref target="OP_SEQUENCE_DESCRIPTION" format="default"/>). are nearly expired, or fully expired (see <xref target="OP_SEQUENCE_DESCRIPTION" format="default"/>).
</t> </t>
</section> </section>
<!-- [auth] RPCSEC_GSS Context Loss by Callback_Path -->
<section numbered="true" toc="default"> <section numbered="true" toc="default">
<name>Connection Loss</name> <name>Connection Loss</name>
<t> <t>
If the client loses the last connection of the session If the client loses the last connection of the session
and wants to retain the session, then it needs to and wants to retain the session, then it needs to
create a new connection, and if, when the client create a new connection, and if, when the client
ID was created, BIND_CONN_TO_SESSION was specified ID was created, BIND_CONN_TO_SESSION was specified
in the spo_must_enforce list, the client <bcp14>MUST</bcp14> use in the spo_must_enforce list, the client <bcp14>MUST</bcp14> use
BIND_CONN_TO_SESSION to associate the connection with BIND_CONN_TO_SESSION to associate the connection with
the session. the session.
skipping to change at line 5200 skipping to change at line 5117
If the connection that was lost was the last one associated with If the connection that was lost was the last one associated with
the backchannel, and the client wants to retain the backchannel and/or the backchannel, and the client wants to retain the backchannel and/or
prevent revocation of recallable state, the client needs to prevent revocation of recallable state, the client needs to
reconnect, and if it does, it reconnect, and if it does, it
<bcp14>MUST</bcp14> associate the connection to the session and backchannel via <bcp14>MUST</bcp14> associate the connection to the session and backchannel via
BIND_CONN_TO_SESSION. BIND_CONN_TO_SESSION.
The server <bcp14>SHOULD</bcp14> indicate when it has no callback connection The server <bcp14>SHOULD</bcp14> indicate when it has no callback connection
via the sr_status_flags result from SEQUENCE. via the sr_status_flags result from SEQUENCE.
</t> </t>
</section> </section>
<!-- [auth] Connection Disconnect -->
<section numbered="true" toc="default"> <section numbered="true" toc="default">
<name>Backchannel GSS Context Loss</name> <name>Backchannel GSS Context Loss</name>
<t> <t>
Via the sr_status_flags result of the SEQUENCE operation or Via the sr_status_flags result of the SEQUENCE operation or
other means, the client will learn if some or all of other means, the client will learn if some or all of
the RPCSEC_GSS contexts it assigned to the backchannel have the RPCSEC_GSS contexts it assigned to the backchannel have
been lost. If the client wants to retain the backchannel and/or been lost. If the client wants to retain the backchannel and/or
not put recallable state subject to revocation, not put recallable state subject to revocation,
the client needs to use BACKCHANNEL_CTL to the client needs to use BACKCHANNEL_CTL to
assign new contexts. assign new contexts.
</t> </t>
</section> </section>
<!-- [auth] Backchannel GSS Context Loss -->
<section anchor="loss_of_session" numbered="true" toc="default"> <section anchor="loss_of_session" numbered="true" toc="default">
<name>Loss of Session</name> <name>Loss of Session</name>
<t> <t>
The replier might lose a record of the session. Causes include: The replier might lose a record of the session. Causes include:
</t> </t>
<ul spacing="normal"> <ul spacing="normal">
<li> <li>
Replier failure and restart. Replier failure and restart.
</li> </li>
skipping to change at line 5281 skipping to change at line 5196
issues: issues:
</t> </t>
<ol spacing="normal" type="1"> <ol spacing="normal" type="1">
<li> <li>
If the client has other connections to If the client has other connections to
other server network addresses other server network addresses
associated with the same session, attempt associated with the same session, attempt
a COMPOUND with a single operation, SEQUENCE, a COMPOUND with a single operation, SEQUENCE,
on each of the other connections. on each of the other connections.
</li> </li>
<!-- [rfced] In Section 2.10.13.1.4, no. 2,
should "so_major" be replaced with "so_major_id"?
Original:
The client might send an EXCHANGE_ID on the
connection that returned NFS4ERR_BADSESSION
to see if there are opportunities for client ID
trunking (i.e., the same client ID and so_major value
are returned).
<li> <li>
If the attempts succeed, the session is still alive, If the attempts succeed, the session is still alive,
and this is a strong indicator that the server's and this is a strong indicator that the server's
network address has moved. network address has moved.
The client might send an EXCHANGE_ID on the The client might send an EXCHANGE_ID on the
connection that returned NFS4ERR_BADSESSION connection that returned NFS4ERR_BADSESSION
to see if there are opportunities for client ID to see if there are opportunities for client ID
trunking (i.e., the same client ID and so_major value trunking (i.e., the same client ID and so_major_id value
are are
returned). The client might use DNS to see if returned). The client might use DNS to see if
the moved network address was replaced with another, the moved network address was replaced with another,
so that the performance and availability benefits of so that the performance and availability benefits of
session trunking can continue. session trunking can continue.
</li> </li>
<li> <li>
If the SEQUENCE requests fail with NFS4ERR_BADSESSION, If the SEQUENCE requests fail with NFS4ERR_BADSESSION,
then the session no longer exists on any of the then the session no longer exists on any of the
server network addresses for which the client has connections server network addresses for which the client has connections
skipping to change at line 5403 skipping to change at line 5308
but lock recovery may still be needed. but lock recovery may still be needed.
</t> </t>
<t> <t>
It is possible that CREATE_SESSION will fail with NFS4ERR_STALE_CLIENTID It is possible that CREATE_SESSION will fail with NFS4ERR_STALE_CLIENTID
(e.g., the server restarts and does not preserve client ID (e.g., the server restarts and does not preserve client ID
state). state).
If so, the client needs to call EXCHANGE_ID, followed by If so, the client needs to call EXCHANGE_ID, followed by
CREATE_SESSION. CREATE_SESSION.
</t> </t>
</section> </section>
<!-- [auth] Loss of Session -->
</section> </section>
<!-- [auth] Events Requiring Client Action -->
<section anchor="Events_Requiring_Server_Action" numbered="true" toc="default"> <section anchor="Events_Requiring_Server_Action" numbered="true" toc="default">
<name>Events Requiring Server Action</name> <name>Events Requiring Server Action</name>
<t> <t>
The following events require server action to recover. The following events require server action to recover.
</t> </t>
<section numbered="true" toc="default"> <section numbered="true" toc="default">
<name>Client Crash and Restart</name> <name>Client Crash and Restart</name>
<t> <t>
As described in <xref target="OP_EXCHANGE_ID" format="default"/>, As described in <xref target="OP_EXCHANGE_ID" format="default"/>,
a restarted client sends EXCHANGE_ID in such a way that it a restarted client sends EXCHANGE_ID in such a way that it
causes the server to delete any sessions it had. causes the server to delete any sessions it had.
</t> </t>
</section> </section>
<!-- [auth] Client Crash and Restart -->
<section anchor="client_crash_no_restart" numbered="true" toc="default"> <section anchor="client_crash_no_restart" numbered="true" toc="default">
<name>Client Crash with No Restart</name> <name>Client Crash with No Restart</name>
<t> <t>
If a client crashes and never comes back, it will never send If a client crashes and never comes back, it will never send
EXCHANGE_ID with its old client owner. Thus, the server has session EXCHANGE_ID with its old client owner. Thus, the server has session
state that will never be used again. After an extended period of time, state that will never be used again. After an extended period of time,
and if the server has resource constraints, it <bcp14>MAY</bcp14> destroy the old and if the server has resource constraints, it <bcp14>MAY</bcp14> destroy the old
session as well as locking state. session as well as locking state.
</t> </t>
</section> </section>
<!-- [auth] Client Crash with No Restart -->
<section numbered="true" toc="default"> <section numbered="true" toc="default">
<name>Extended Network Partition</name> <name>Extended Network Partition</name>
<t> <t>
To the server, the extended network partition may be no To the server, the extended network partition may be no
different from a different from a
client crash with no client crash with no
restart (see restart (see
<xref target="client_crash_no_restart" format="default"/>). <xref target="client_crash_no_restart" format="default"/>).
Unless the server can discern that there is Unless the server can discern that there is
a network partition, it is free to treat the a network partition, it is free to treat the
situation as if the client has crashed permanently. situation as if the client has crashed permanently.
</t> </t>
</section> </section>
<!-- [auth] "Extended Network Partition" -->
<section numbered="true" toc="default"> <section numbered="true" toc="default">
<name>Backchannel Connection Loss</name> <name>Backchannel Connection Loss</name>
<t> <t>
If there were callback requests outstanding at the time If there were callback requests outstanding at the time
of a connection loss, then the server of a connection loss, then the server
<bcp14>MUST</bcp14> retry the requests, as described in <bcp14>MUST</bcp14> retry the requests, as described in
<xref target="Retry_and_Replay" format="default"/>. Note that it <xref target="Retry_and_Replay" format="default"/>. Note that it
is not necessary to retry requests over a connection is not necessary to retry requests over a connection
with the same source network address or the same destination with the same source network address or the same destination
network address as the lost connection. As long as network address as the lost connection. As long as
skipping to change at line 5472 skipping to change at line 5372
If the connection lost is the last one associated with the backchannel, If the connection lost is the last one associated with the backchannel,
then the server <bcp14>MUST</bcp14> indicate that in the sr_status_flags field of then the server <bcp14>MUST</bcp14> indicate that in the sr_status_flags field of
every SEQUENCE reply until the backchannel is re-established. every SEQUENCE reply until the backchannel is re-established.
There are two situations, each of which uses different There are two situations, each of which uses different
status flags: no connectivity for the session's backchannel status flags: no connectivity for the session's backchannel
and no connectivity for any session backchannel of the client. and no connectivity for any session backchannel of the client.
See <xref target="OP_SEQUENCE" format="default"/> for a description of See <xref target="OP_SEQUENCE" format="default"/> for a description of
the appropriate flags in sr_status_flags. the appropriate flags in sr_status_flags.
</t> </t>
</section> </section>
<!-- [auth] Backchannel Connection Loss -->
<section numbered="true" toc="default"> <section numbered="true" toc="default">
<name>GSS Context Loss</name> <name>GSS Context Loss</name>
<t> <t>
The server <bcp14>SHOULD</bcp14> monitor when the number of RPCSEC_GSS The server <bcp14>SHOULD</bcp14> monitor when the number of RPCSEC_GSS
handles assigned to the backchannel reaches one, and when that handles assigned to the backchannel reaches one, and when that
one handle is near expiry (i.e., between one handle is near expiry (i.e., between
one and two periods of lease time), and one and two periods of lease time), and
indicate so in the sr_status_flags field of all SEQUENCE replies. indicate so in the sr_status_flags field of all SEQUENCE replies.
The server <bcp14>MUST</bcp14> indicate when all of the The server <bcp14>MUST</bcp14> indicate when all of the
backchannel's assigned RPCSEC_GSS handles backchannel's assigned RPCSEC_GSS handles
have expired via the sr_status_flags field of all SEQUENCE replies. have expired via the sr_status_flags field of all SEQUENCE replies.
</t> </t>
</section> </section>
<!-- [auth] GSS Context Loss -->
</section> </section>
<!-- [auth] Events Requiring Server Action -->
</section> </section>
<!-- [auth] Session Mechanics - Recovery -->
<section anchor="pnfs_and_sessions" numbered="true" toc="default"> <section anchor="pnfs_and_sessions" numbered="true" toc="default">
<name>Parallel NFS and Sessions</name> <name>Parallel NFS and Sessions</name>
<t> <t>
A client and server can potentially be a non-pNFS implementation, A client and server can potentially be a non-pNFS implementation,
a metadata server implementation, a data server implementation, or two or a metadata server implementation, a data server implementation, or two or
three types of implementations. The EXCHGID4_FLAG_USE_NON_PNFS, three types of implementations. The EXCHGID4_FLAG_USE_NON_PNFS,
EXCHGID4_FLAG_USE_PNFS_MDS, and EXCHGID4_FLAG_USE_PNFS_DS flags EXCHGID4_FLAG_USE_PNFS_MDS, and EXCHGID4_FLAG_USE_PNFS_DS flags
(not mutually exclusive) are passed in the EXCHANGE_ID arguments (not mutually exclusive) are passed in the EXCHANGE_ID arguments
and results to allow the client to indicate how it wants to use sessions created and results to allow the client to indicate how it wants to use sessions created
under the client ID, and to allow the server to indicate how it under the client ID, and to allow the server to indicate how it
will allow the sessions to be used. will allow the sessions to be used.
See <xref target="pnfs_session_stuff" format="default"/> for pNFS sessions considerations. See <xref target="pnfs_session_stuff" format="default"/> for pNFS sessions considerations.
</t> </t>
</section> </section>
<!-- [auth] Parallel NFS and Sessions -->
</section> </section>
<!-- [auth] Session -->
</section> </section>
<!-- [auth] Core Infrastructure -->
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- [auth] Copyright (C) The IETF Trust (2007-2008) -->
<!-- [auth] Copyright (C) The Internet Society (2006) -->
<section numbered="true" toc="default"> <section numbered="true" toc="default">
<name>Protocol Constants and Data Types</name> <name>Protocol Constants and Data Types</name>
<t> <t>
The syntax and semantics to describe the data types of the NFSv4.1 The syntax and semantics to describe the data types of the NFSv4.1
protocol are defined in the XDR (<xref target="RFC4506" format="default">RFC 4506</xref>) and RPC protocol are defined in the XDR (<xref target="RFC4506" format="default">RFC 4506</xref>) and RPC
(<xref target="RFC5531" format="default">RFC 5531</xref>) documents. The next sections (<xref target="RFC5531" format="default">RFC 5531</xref>) documents. The next sections
build upon the XDR data types to define constants, types, and structures build upon the XDR data types to define constants, types, and structures
specific to this protocol. The full list of XDR data types is in <xref target="RFC5662" format="default"/>. specific to this protocol. The full list of XDR data types is in <xref target="RFC5662" format="default"/>.
</t> </t>
<section numbered="true" toc="default"> <section numbered="true" toc="default">
<name>Basic Constants</name> <name>Basic Constants</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
const NFS4_FHSIZE = 128; const NFS4_FHSIZE = 128;
const NFS4_VERIFIER_SIZE = 8; const NFS4_VERIFIER_SIZE = 8;
const NFS4_OPAQUE_LIMIT = 1024; const NFS4_OPAQUE_LIMIT = 1024;
const NFS4_SESSIONID_SIZE = 16; const NFS4_SESSIONID_SIZE = 16;
const NFS4_INT64_MAX = 0x7fffffffffffffff; const NFS4_INT64_MAX = 0x7fffffffffffffff;
const NFS4_UINT64_MAX = 0xffffffffffffffff; const NFS4_UINT64_MAX = 0xffffffffffffffff;
const NFS4_INT32_MAX = 0x7fffffff; const NFS4_INT32_MAX = 0x7fffffff;
const NFS4_UINT32_MAX = 0xffffffff; const NFS4_UINT32_MAX = 0xffffffff;
skipping to change at line 5775 skipping to change at line 5665
<td align="left"><t>typedef opaque verifier4[NFS4_VERIFIER_SIZE];</t> <td align="left"><t>typedef opaque verifier4[NFS4_VERIFIER_SIZE];</t>
<t>Verifier used for various operations (COMMIT, CREATE, <t>Verifier used for various operations (COMMIT, CREATE,
EXCHANGE_ID, OPEN, READDIR, WRITE) NFS4_VERIFIER_SIZE is defined EXCHANGE_ID, OPEN, READDIR, WRITE) NFS4_VERIFIER_SIZE is defined
as 8.</t> as 8.</t>
</td> </td>
</tr> </tr>
</tbody> </tbody>
</table> </table>
<t>End of Base Data Types</t> <t>End of Base Data Types</t>
</section> </section>
<!-- [auth] start here for the structured data types -->
<section numbered="true" toc="default"> <section numbered="true" toc="default">
<name>Structured Data Types</name> <name>Structured Data Types</name>
<section toc="exclude" anchor="nfstime4" numbered="true"> <section toc="exclude" anchor="nfstime4" numbered="true">
<name>nfstime4</name> <name>nfstime4</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct nfstime4 { struct nfstime4 {
int64_t seconds; int64_t seconds;
uint32_t nseconds; uint32_t nseconds;
}; };
]]></sourcecode> ]]></sourcecode>
<t> <t>
The nfstime4 data type gives the number of seconds and The nfstime4 data type gives the number of seconds and
nanoseconds since midnight or zero hour January 1, 1970 nanoseconds since midnight or zero hour January 1, 1970
Coordinated Universal Time (UTC). Values greater than zero Coordinated Universal Time (UTC). Values greater than zero
for the seconds field denote dates after the zero hour January 1, for the seconds field denote dates after the zero hour January 1,
skipping to change at line 5814 skipping to change at line 5703
server converts to and from its local representation of time server converts to and from its local representation of time
when processing time values, preserving as much accuracy as when processing time values, preserving as much accuracy as
possible. If the precision of timestamps stored for a possible. If the precision of timestamps stored for a
file system object is less than defined, loss of precision can file system object is less than defined, loss of precision can
occur. An adjunct time maintenance protocol is <bcp14>RECOMMENDED</bcp14> to occur. An adjunct time maintenance protocol is <bcp14>RECOMMENDED</bcp14> to
reduce client and server time skew. reduce client and server time skew.
</t> </t>
</section> </section>
<section toc="exclude" anchor="time_how4" numbered="true"> <section toc="exclude" anchor="time_how4" numbered="true">
<name>time_how4</name> <name>time_how4</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
enum time_how4 { enum time_how4 {
SET_TO_SERVER_TIME4 = 0, SET_TO_SERVER_TIME4 = 0,
SET_TO_CLIENT_TIME4 = 1 SET_TO_CLIENT_TIME4 = 1
}; };
]]></sourcecode> ]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="settime4" numbered="true"> <section toc="exclude" anchor="settime4" numbered="true">
<name>settime4</name> <name>settime4</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
union settime4 switch (time_how4 set_it) { union settime4 switch (time_how4 set_it) {
case SET_TO_CLIENT_TIME4: case SET_TO_CLIENT_TIME4:
nfstime4 time; nfstime4 time;
default: default:
void; void;
}; };
]]></sourcecode> ]]></sourcecode>
<t> <t>
The time_how4 and settime4 data types are used The time_how4 and settime4 data types are used
for setting timestamps in file object attributes. If set_it is SET_TO_SERVER_TIME4, then the server for setting timestamps in file object attributes. If set_it is SET_TO_SERVER_TIME4, then the server
uses its local representation of time for the time value. uses its local representation of time for the time value.
</t> </t>
</section> </section>
<section toc="exclude" anchor="specdata4" numbered="true"> <section toc="exclude" anchor="specdata4" numbered="true">
<name>specdata4</name> <name>specdata4</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct specdata4 { struct specdata4 {
uint32_t specdata1; /* major device number */ uint32_t specdata1; /* major device number */
uint32_t specdata2; /* minor device number */ uint32_t specdata2; /* minor device number */
}; };
]]></sourcecode> ]]></sourcecode>
<t> <t>
This data type represents the device numbers for the device file This data type represents the device numbers for the device file
types NF4CHR and NF4BLK. types NF4CHR and NF4BLK.
</t> </t>
</section> </section>
<section toc="exclude" anchor="fsid4" numbered="true"> <section toc="exclude" anchor="fsid4" numbered="true">
<name>fsid4</name> <name>fsid4</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct fsid4 { struct fsid4 {
uint64_t major; uint64_t major;
uint64_t minor; uint64_t minor;
}; };
]]></sourcecode> ]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="chg_policy4" numbered="true"> <section toc="exclude" anchor="chg_policy4" numbered="true">
<name>change_policy4</name> <name>change_policy4</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct change_policy4 { struct change_policy4 {
uint64_t cp_major; uint64_t cp_major;
uint64_t cp_minor; uint64_t cp_minor;
}; };
]]></sourcecode> ]]></sourcecode>
<t> <t>
The change_policy4 data type is used for the change_policy The change_policy4 data type is used for the change_policy
<bcp14>RECOMMENDED</bcp14> attribute. It provides change sequencing indication <bcp14>RECOMMENDED</bcp14> attribute. It provides change sequencing indication
analogous to the change attribute. To enable the server to analogous to the change attribute. To enable the server to
present a value valid across server re-initialization without present a value valid across server re-initialization without
requiring persistent storage, two 64-bit quantities are used, requiring persistent storage, two 64-bit quantities are used,
allowing one to be a server instance ID and the second to be allowing one to be a server instance ID and the second to be
incremented non-persistently, within a given server instance. incremented non-persistently, within a given server instance.
</t> </t>
</section> </section>
<section toc="exclude" anchor="fattr4" numbered="true"> <section toc="exclude" anchor="fattr4" numbered="true">
<name>fattr4</name> <name>fattr4</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct fattr4 { struct fattr4 {
bitmap4 attrmask; bitmap4 attrmask;
attrlist4 attr_vals; attrlist4 attr_vals;
}; };
]]></sourcecode> ]]></sourcecode>
<t> <t>
The fattr4 data type is used to represent file and directory attributes. The fattr4 data type is used to represent file and directory attributes.
</t> </t>
<t> <t>
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).
</t> </t>
<artwork name="" type="" align="left" alt=""><![CDATA[ <artwork name="" type="" align="left" alt=""><![CDATA[
0 1 0 1
+-----------+-----------+-----------+-- +-----------+-----------+-----------+--
| count | 31 .. 0 | 63 .. 32 | | count | 31 .. 0 | 63 .. 32 |
+-----------+-----------+-----------+-- +-----------+-----------+-----------+--
]]></artwork> ]]></artwork>
</section> </section>
<section toc="exclude" anchor="change_info4" numbered="true"> <section toc="exclude" anchor="change_info4" numbered="true">
<name>change_info4</name> <name>change_info4</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct change_info4 { struct change_info4 {
bool atomic; bool atomic;
changeid4 before; changeid4 before;
changeid4 after; changeid4 after;
}; };
]]></sourcecode> ]]></sourcecode>
<t> <t>
This data type is used with the CREATE, LINK, OPEN, REMOVE, and RENAME This data type is used with the CREATE, LINK, OPEN, REMOVE, and RENAME
operations to let the client know the value of the change attribute operations to let the client know the value of the change attribute
for the directory in which the target file system object resides. for the directory in which the target file system object resides.
</t> </t>
</section> </section>
<section toc="exclude" anchor="netaddr4" numbered="true"> <section toc="exclude" anchor="netaddr4" numbered="true">
<name>netaddr4</name> <name>netaddr4</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct netaddr4 { struct netaddr4 {
/* see struct rpcb in RFC 1833 */ /* see struct rpcb in RFC 1833 */
string na_r_netid<>; /* network id */ string na_r_netid<>; /* network id */
string na_r_addr<>; /* universal address */ string na_r_addr<>; /* universal address */
}; };
]]></sourcecode> ]]></sourcecode>
<t> <t>
The netaddr4 data type is used to identify network transport endpoints. The netaddr4 data type is used to identify network transport endpoints.
The na_r_netid and na_r_addr fields respectively contain a netid The na_r_netid and na_r_addr fields respectively contain a netid
and uaddr. The netid and uaddr concepts are defined in and uaddr. The netid and uaddr concepts are defined in
<xref target="RFC5665" format="default"/>. The netid and uaddr formats for <xref target="RFC5665" format="default"/>. The netid and uaddr formats for
TCP over IPv4 and TCP over IPv6 are defined in <xref target="RFC5665" format="default"/>, TCP over IPv4 and TCP over IPv6 are defined in <xref target="RFC5665" format="default"/>,
specifically Tables 2 and 3 and in specifically Tables 2 and 3 and in
Sections <xref target="RFC5665" section="5.2.3.3" sectionFormat="bare"/> and <xref target="RFC5665" section="5.2.3.4" sectionFormat="bare"/>. Sections <xref target="RFC5665" section="5.2.3.3" sectionFormat="bare"/> and <xref target="RFC5665" section="5.2.3.4" sectionFormat="bare"/>.
</t> </t>
</section> </section>
<section toc="exclude" anchor="state_owner4" numbered="true"> <section toc="exclude" anchor="state_owner4" numbered="true">
<name>state_owner4</name> <name>state_owner4</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct state_owner4 { struct state_owner4 {
clientid4 clientid; clientid4 clientid;
opaque owner<NFS4_OPAQUE_LIMIT>; opaque owner<NFS4_OPAQUE_LIMIT>;
}; };
typedef state_owner4 open_owner4; typedef state_owner4 open_owner4;
typedef state_owner4 lock_owner4; typedef state_owner4 lock_owner4;
]]></sourcecode> ]]></sourcecode>
<t> <t>
The state_owner4 data type is the base type for the The state_owner4 data type is the base type for the
skipping to change at line 5968 skipping to change at line 5857
<section toc="exclude" anchor="lock_owner4" numbered="true"> <section toc="exclude" anchor="lock_owner4" numbered="true">
<name>lock_owner4</name> <name>lock_owner4</name>
<t> <t>
This structure is used to identify the owner of byte-range This structure is used to identify the owner of byte-range
locking state. locking state.
</t> </t>
</section> </section>
</section> </section>
<section toc="exclude" anchor="open_to_lock_owner4" numbered="true"> <section toc="exclude" anchor="open_to_lock_owner4" numbered="true">
<name>open_to_lock_owner4</name> <name>open_to_lock_owner4</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct open_to_lock_owner4 { struct open_to_lock_owner4 {
seqid4 open_seqid; seqid4 open_seqid;
stateid4 open_stateid; stateid4 open_stateid;
seqid4 lock_seqid; seqid4 lock_seqid;
lock_owner4 lock_owner; lock_owner4 lock_owner;
}; };
]]></sourcecode> ]]></sourcecode>
<t> <t>
This data type is used for the first LOCK operation done for This data type is used for the first LOCK operation done for
an open_owner4. It provides both the open_stateid and an open_owner4. It provides both the open_stateid and
lock_owner, such that the transition is made from a valid lock_owner, such that the transition is made from a valid
open_stateid sequence to that of the new lock_stateid open_stateid sequence to that of the new lock_stateid
sequence. Using this mechanism avoids the confirmation of the sequence. Using this mechanism avoids the confirmation of the
lock_owner/lock_seqid pair since it is tied to established lock_owner/lock_seqid pair since it is tied to established
state in the form of the open_stateid/open_seqid. state in the form of the open_stateid/open_seqid.
</t> </t>
</section> </section>
<section toc="exclude" anchor="stateid4" numbered="true"> <section toc="exclude" anchor="stateid4" numbered="true">
<name>stateid4</name> <name>stateid4</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct stateid4 { struct stateid4 {
uint32_t seqid; uint32_t seqid;
opaque other[12]; opaque other[12];
}; };
]]></sourcecode> ]]></sourcecode>
<t> <t>
This data type is used for the various state sharing This data type is used for the various state sharing
mechanisms between the client and server. The client mechanisms between the client and server. The client
never modifies a value of data type stateid. never modifies a value of data type stateid.
The starting value of the The starting value of the
"seqid" field is undefined. The server is required to "seqid" field is undefined. The server is required to
increment the "seqid" field by one at each transition increment the "seqid" field by one at each transition
of the stateid. This is important since the client will of the stateid. This is important since the client will
inspect the seqid in OPEN stateids to determine the order of inspect the seqid in OPEN stateids to determine the order of
OPEN processing done by the server. OPEN processing done by the server.
</t> </t>
</section> </section>
<section toc="exclude" anchor="layouttype4" numbered="true"> <section toc="exclude" anchor="layouttype4" numbered="true">
<name>layouttype4</name> <name>layouttype4</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
enum layouttype4 { enum layouttype4 {
LAYOUT4_NFSV4_1_FILES = 0x1, LAYOUT4_NFSV4_1_FILES = 0x1,
LAYOUT4_OSD2_OBJECTS = 0x2, LAYOUT4_OSD2_OBJECTS = 0x2,
LAYOUT4_BLOCK_VOLUME = 0x3 LAYOUT4_BLOCK_VOLUME = 0x3
}; };
]]></sourcecode> ]]></sourcecode>
<t> <t>
This data type indicates what type of layout is being used. This data type indicates what type of layout is being used.
The file server advertises the The file server advertises the
layout types it supports through the fs_layout_type file layout types it supports through the fs_layout_type file
skipping to change at line 6044 skipping to change at line 5933
file layout type, as defined in <xref target="file_layout_type" format="default"/>, is to be used. The LAYOUT4_OSD2_OBJECTS file layout type, as defined in <xref target="file_layout_type" format="default"/>, is to be used. The LAYOUT4_OSD2_OBJECTS
enumeration specifies that the object layout, as defined in enumeration specifies that the object layout, as defined in
<xref target="RFC5664" format="default"/>, is to be used. Similarly, <xref target="RFC5664" format="default"/>, is to be used. Similarly,
the LAYOUT4_BLOCK_VOLUME enumeration specifies that the block/volume the LAYOUT4_BLOCK_VOLUME enumeration specifies that the block/volume
layout, as defined in <xref target="RFC5663" format="default"/>, is to be layout, as defined in <xref target="RFC5663" format="default"/>, is to be
used. used.
</t> </t>
</section> </section>
<section toc="exclude" anchor="deviceid4" numbered="true"> <section toc="exclude" anchor="deviceid4" numbered="true">
<name>deviceid4</name> <name>deviceid4</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
const NFS4_DEVICEID4_SIZE = 16; const NFS4_DEVICEID4_SIZE = 16;
typedef opaque deviceid4[NFS4_DEVICEID4_SIZE]; typedef opaque deviceid4[NFS4_DEVICEID4_SIZE];
]]></sourcecode> ]]></sourcecode>
<t> <t>
Layout information includes device IDs that Layout information includes device IDs that
specify a storage device through a compact handle. specify a storage device through a compact handle.
Addressing and type information is obtained Addressing and type information is obtained
with the GETDEVICEINFO operation. Device IDs with the GETDEVICEINFO operation. Device IDs
are not guaranteed to be valid across metadata are not guaranteed to be valid across metadata
server restarts. A device ID is unique per client server restarts. A device ID is unique per client
ID and layout type. See <xref target="device_ids" format="default"/> for more details. ID and layout type. See <xref target="device_ids" format="default"/> for more details.
</t> </t>
</section> </section>
<section toc="exclude" anchor="device_addr4" numbered="true"> <section toc="exclude" anchor="device_addr4" numbered="true">
<name>device_addr4</name> <name>device_addr4</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct device_addr4 { struct device_addr4 {
layouttype4 da_layout_type; layouttype4 da_layout_type;
opaque da_addr_body<>; opaque da_addr_body<>;
}; };
]]></sourcecode> ]]></sourcecode>
<t> <t>
The device address is used to set up a communication channel The device address is used to set up a communication channel
with the storage device. Different layout types will require with the storage device. Different layout types will require
different data types to define how they communicate different data types to define how they communicate
with storage devices. The opaque da_addr_body field is with storage devices. The opaque da_addr_body field is
skipping to change at line 6089 skipping to change at line 5978
number. This is sufficient for the clients to communicate number. This is sufficient for the clients to communicate
with the NFSv4.1 storage devices, and may be sufficient for with the NFSv4.1 storage devices, and may be sufficient for
other layout types as well. Device types for object-based storage other layout types as well. Device types for object-based storage
devices and block storage devices (e.g., Small Computer System devices and block storage devices (e.g., Small Computer System
Interface (SCSI) volume labels) Interface (SCSI) volume labels)
are defined by their respective layout specifications. are defined by their respective layout specifications.
</t> </t>
</section> </section>
<section toc="exclude" anchor="layout_content4" numbered="true"> <section toc="exclude" anchor="layout_content4" numbered="true">
<name>layout_content4</name> <name>layout_content4</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct layout_content4 { struct layout_content4 {
layouttype4 loc_type; layouttype4 loc_type;
opaque loc_body<>; opaque loc_body<>;
}; };
]]></sourcecode> ]]></sourcecode>
<t> <t>
The loc_body field is interpreted based on the layout type (loc_type). The loc_body field is interpreted based on the layout type (loc_type).
This document defines the loc_body for the NFSv4.1 This document defines the loc_body for the NFSv4.1
file layout type; see <xref target="file_data_types" format="default"/> for its definition. file layout type; see <xref target="file_data_types" format="default"/> for its definition.
</t> </t>
</section> </section>
<section toc="exclude" anchor="layout4" numbered="true"> <section toc="exclude" anchor="layout4" numbered="true">
<name>layout4</name> <name>layout4</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct layout4 { struct layout4 {
offset4 lo_offset; offset4 lo_offset;
length4 lo_length; length4 lo_length;
layoutiomode4 lo_iomode; layoutiomode4 lo_iomode;
layout_content4 lo_content; layout_content4 lo_content;
}; };
]]></sourcecode> ]]></sourcecode>
<t> <t>
The layout4 data type defines a layout for a file. The layout The layout4 data type defines a layout for a file. The layout
type specific data is opaque within lo_content. type specific data is opaque within lo_content.
Since layouts are sub-dividable, the offset Since layouts are sub-dividable, the offset
and length together with the file's filehandle, the client ID, and length together with the file's filehandle, the client ID,
iomode, and layout type identify the layout. iomode, and layout type identify the layout.
</t> </t>
</section> </section>
<section toc="exclude" anchor="layoutupdate4" numbered="true"> <section toc="exclude" anchor="layoutupdate4" numbered="true">
<name>layoutupdate4</name> <name>layoutupdate4</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct layoutupdate4 { struct layoutupdate4 {
layouttype4 lou_type; layouttype4 lou_type;
opaque lou_body<>; opaque lou_body<>;
}; };
]]></sourcecode> ]]></sourcecode>
<t> <t>
The layoutupdate4 data type is used by the client to return The layoutupdate4 data type is used by the client to return
updated layout information to the metadata server via the updated layout information to the metadata server via the
LAYOUTCOMMIT (<xref target="OP_LAYOUTCOMMIT" format="default"/>) operation. LAYOUTCOMMIT (<xref target="OP_LAYOUTCOMMIT" format="default"/>) operation.
This data type provides a channel to pass This data type provides a channel to pass
skipping to change at line 6145 skipping to change at line 6034
list of reserved blocks that were written. The contents of list of reserved blocks that were written. The contents of
the opaque lou_body argument are determined by the layout type. the opaque lou_body argument are determined by the layout type.
The NFSv4.1 file-based layout The NFSv4.1 file-based layout
does not use this data type; if lou_type is LAYOUT4_NFSV4_1_FILES, does not use this data type; if lou_type is LAYOUT4_NFSV4_1_FILES,
the lou_body field <bcp14>MUST</bcp14> the lou_body field <bcp14>MUST</bcp14>
have a zero length. have a zero length.
</t> </t>
</section> </section>
<section toc="exclude" anchor="layouthint4" numbered="true"> <section toc="exclude" anchor="layouthint4" numbered="true">
<name>layouthint4</name> <name>layouthint4</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct layouthint4 { struct layouthint4 {
layouttype4 loh_type; layouttype4 loh_type;
opaque loh_body<>; opaque loh_body<>;
}; };
]]></sourcecode> ]]></sourcecode>
<t> <t>
The layouthint4 data type is used by the client to pass in a The layouthint4 data type is used by the client to pass in a
hint about the type of layout it would like created for a particular hint about the type of layout it would like created for a particular
file. It is the data type specified by the layout_hint file. It is the data type specified by the layout_hint
attribute described in <xref target="attrdef_layout_hint" format="default"/>. attribute described in <xref target="attrdef_layout_hint" format="default"/>.
The metadata server may ignore the hint The metadata server may ignore the hint
or may selectively ignore fields within the hint. This hint should or may selectively ignore fields within the hint. This hint should
be provided at create time as part of the initial attributes within be provided at create time as part of the initial attributes within
OPEN. The loh_body field is specific to the type of layout (loh_type). OPEN. The loh_body field is specific to the type of layout (loh_type).
The NFSv4.1 file-based layout uses the nfsv4_1_file_layouthint4 The NFSv4.1 file-based layout uses the nfsv4_1_file_layouthint4
data type as defined in <xref target="file_data_types" format="default"/>. data type as defined in <xref target="file_data_types" format="default"/>.
</t> </t>
</section> </section>
<section toc="exclude" anchor="layoutiomode4" numbered="true"> <section toc="exclude" anchor="layoutiomode4" numbered="true">
<name>layoutiomode4</name> <name>layoutiomode4</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
enum layoutiomode4 { enum layoutiomode4 {
LAYOUTIOMODE4_READ = 1, LAYOUTIOMODE4_READ = 1,
LAYOUTIOMODE4_RW = 2, LAYOUTIOMODE4_RW = 2,
LAYOUTIOMODE4_ANY = 3 LAYOUTIOMODE4_ANY = 3
}; };
]]></sourcecode> ]]></sourcecode>
<t> <t>
The iomode specifies whether the client intends to just read or both The iomode specifies whether the client intends to just read or both
read and write the data represented by the read and write the data represented by the
layout. While the LAYOUTIOMODE4_ANY iomode <bcp14>MUST NOT</bcp14> be used in layout. While the LAYOUTIOMODE4_ANY iomode <bcp14>MUST NOT</bcp14> be used in
skipping to change at line 6189 skipping to change at line 6078
operations. The LAYOUTIOMODE4_ANY iomode operations. The LAYOUTIOMODE4_ANY iomode
specifies that layouts pertaining to both LAYOUTIOMODE4_READ specifies that layouts pertaining to both LAYOUTIOMODE4_READ
and LAYOUTIOMODE4_RW iomodes are being returned or recalled, and LAYOUTIOMODE4_RW iomodes are being returned or recalled,
respectively. The metadata server's use of the iomode may respectively. The metadata server's use of the iomode may
depend on the layout type being used. The storage devices <bcp14>MAY</bcp14> depend on the layout type being used. The storage devices <bcp14>MAY</bcp14>
validate I/O accesses against the iomode and reject invalid accesses. validate I/O accesses against the iomode and reject invalid accesses.
</t> </t>
</section> </section>
<section toc="exclude" anchor="nfs_impl_id4" numbered="true"> <section toc="exclude" anchor="nfs_impl_id4" numbered="true">
<name>nfs_impl_id4</name> <name>nfs_impl_id4</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct nfs_impl_id4 { struct nfs_impl_id4 {
utf8str_cis nii_domain; utf8str_cis nii_domain;
utf8str_cs nii_name; utf8str_cs nii_name;
nfstime4 nii_date; nfstime4 nii_date;
}; };
]]></sourcecode> ]]></sourcecode>
<t> <t>
This data type is used to identify client and server This data type is used to identify client and server
implementation details. The nii_domain field is the DNS domain implementation details. The nii_domain field is the DNS domain
name with which the implementor is associated. The nii_name name with which the implementor is associated. The nii_name
field is the product name of the implementation and is field is the product name of the implementation and is
completely free form. It is <bcp14>RECOMMENDED</bcp14> that the nii_name be completely free form. It is <bcp14>RECOMMENDED</bcp14> that the nii_name be
used to distinguish machine architecture, machine platforms, used to distinguish machine architecture, machine platforms,
revisions, versions, and patch levels. The nii_date field is revisions, versions, and patch levels. The nii_date field is
the timestamp of when the software instance was published or the timestamp of when the software instance was published or
built. built.
</t> </t>
</section> </section>
<section toc="exclude" anchor="threshold_item4" numbered="true"> <section toc="exclude" anchor="threshold_item4" numbered="true">
<name>threshold_item4</name> <name>threshold_item4</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct threshold_item4 { struct threshold_item4 {
layouttype4 thi_layout_type; layouttype4 thi_layout_type;
bitmap4 thi_hintset; bitmap4 thi_hintset;
opaque thi_hintlist<>; opaque thi_hintlist<>;
}; };
]]></sourcecode> ]]></sourcecode>
<t> <t>
This data type contains a list of hints specific to This data type contains a list of hints specific to
a layout type for helping the client determine when a layout type for helping the client determine when
it should send I/O directly through the metadata it should send I/O directly through the metadata
skipping to change at line 6288 skipping to change at line 6177
<td align="left"> <td align="left">
For write I/O sizes below this threshold, it is <bcp14>RECOMMENDED</bcp14> to For write I/O sizes below this threshold, it is <bcp14>RECOMMENDED</bcp14> to
write data through the MDS. write data through the MDS.
</td> </td>
</tr> </tr>
</tbody> </tbody>
</table> </table>
</section> </section>
<section toc="exclude" anchor="mdsthreshold4" numbered="true"> <section toc="exclude" anchor="mdsthreshold4" numbered="true">
<name>mdsthreshold4</name> <name>mdsthreshold4</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct mdsthreshold4 { struct mdsthreshold4 {
threshold_item4 mth_hints<>; threshold_item4 mth_hints<>;
}; };
]]></sourcecode> ]]></sourcecode>
<t> <t>
This data type holds an array of elements of data type This data type holds an array of elements of data type
threshold_item4, threshold_item4,
each of which is valid for a particular layout type. An array each of which is valid for a particular layout type. An array
is necessary because a server can support multiple layout types is necessary because a server can support multiple layout types
for a single file. for a single file.
</t> </t>
</section> </section>
</section> </section>
</section> </section>
<!-- [auth] End of Data Types -->
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- [auth] Copyright (C) The IETF Trust (2007-2008) -->
<!-- [auth] Copyright (C) The Internet Society (2006) -->
<section anchor="Filehandles" numbered="true" toc="default"> <section anchor="Filehandles" numbered="true" toc="default">
<name>Filehandles</name> <name>Filehandles</name>
<t> <t>
The filehandle in the NFS protocol is a per-server unique identifier The filehandle in the NFS protocol is a per-server unique identifier
for a file system object. The contents of the filehandle are opaque for a file system object. The contents of the filehandle are opaque
to the client. Therefore, the server is responsible for translating to the client. Therefore, the server is responsible for translating
the filehandle to an internal representation of the file system the filehandle to an internal representation of the file system
object. object.
</t> </t>
<section numbered="true" toc="default"> <section numbered="true" toc="default">
skipping to change at line 6546 skipping to change at line 6431
of the pseudo file systems used to bridge exports. See of the pseudo file systems used to bridge exports. See
<xref target="pseudo_fs_volatility" format="default"/> for a discussion of this. <xref target="pseudo_fs_volatility" format="default"/> for a discussion of this.
</t> </t>
</section> </section>
</section> </section>
<section numbered="true" toc="default"> <section numbered="true" toc="default">
<name>One Method of Constructing a Volatile Filehandle</name> <name>One Method of Constructing a Volatile Filehandle</name>
<t> <t>
A volatile filehandle, while opaque to the client, could contain: A volatile filehandle, while opaque to the client, could contain:
</t> </t>
<sourcecode type=""><![CDATA[ <sourcecode type="pseudocode"><![CDATA[
[volatile bit = 1 | server boot time | slot | generation number] [volatile bit = 1 | server boot time | slot | generation number]
]]></sourcecode> ]]></sourcecode>
<ul> <ul>
<li>slot is an index in the server volatile filehandle table</li> <li>slot is an index in the server volatile filehandle table</li>
<li>generation number is the generation number for the table entry/slot</li> <li>generation number is the generation number for the table entry/slot</li>
</ul> </ul>
<t> <t>
When the client presents a volatile filehandle, the server makes the When the client presents a volatile filehandle, the server makes the
following checks, which assume that the check for the volatile bit has following checks, which assume that the check for the volatile bit has
passed. If the server boot time is less than the current server boot passed. If the server boot time is less than the current server boot
skipping to change at line 6603 skipping to change at line 6488
has been renamed. If the file was renamed by another client, again it has been renamed. If the file was renamed by another client, again it
is possible that the original client will not be able to recover. is possible that the original client will not be able to recover.
However, in the case that the client itself is renaming the file and However, in the case that the client itself is renaming the file and
the file is open, it is possible that the client may be able to the file is open, it is possible that the client may be able to
recover. The client can determine the new pathname based on the recover. The client can determine the new pathname based on the
processing of the rename request. The client can then regenerate the processing of the rename request. The client can then regenerate the
new filehandle based on the new pathname. The client could also use new filehandle based on the new pathname. The client could also use
the COMPOUND procedure to construct a series of operations the COMPOUND procedure to construct a series of operations
like: like:
</t> </t>
<sourcecode type=""><![CDATA[ <sourcecode type="nfsv4compound"><![CDATA[
RENAME A B RENAME A B
LOOKUP B LOOKUP B
GETFH GETFH
]]></sourcecode> ]]></sourcecode>
<t> <t>
Note that the COMPOUND procedure does not provide atomicity. This Note that the COMPOUND procedure does not provide atomicity. This
example only reduces the overhead of recovering from an expired example only reduces the overhead of recovering from an expired
filehandle. filehandle.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- [auth] Copyright (C) The IETF Trust (2007-2008) -->
<!-- [auth] Copyright (C) The Internet Society (2006) -->
<section anchor="file_attributes" numbered="true" toc="default"> <section anchor="file_attributes" numbered="true" toc="default">
<name>File Attributes</name> <name>File Attributes</name>
<t> <t>
To meet the requirements of extensibility and increased To meet the requirements of extensibility and increased
interoperability with non-UNIX platforms, attributes need to be handled interoperability with non-UNIX platforms, attributes need to be handled
in a flexible manner. The NFSv3 fattr3 structure contains a in a flexible manner. The NFSv3 fattr3 structure contains a
fixed list of attributes that not all clients and servers are able to fixed list of attributes that not all clients and servers are able to
support or care about. The fattr3 structure cannot be extended as support or care about. The fattr3 structure cannot be extended as
new needs arise and it provides no way to indicate non-support. With new needs arise and it provides no way to indicate non-support. With
the NFSv4.1 protocol, the client is able to query what attributes the NFSv4.1 protocol, the client is able to query what attributes
skipping to change at line 6657 skipping to change at line 6539
<t> <t>
Named attributes are accessed by the new OPENATTR operation, which Named attributes are accessed by the new OPENATTR operation, which
accesses a hidden directory of attributes associated with a file accesses a hidden directory of attributes associated with a file
system object. OPENATTR takes a filehandle for the object and returns system object. OPENATTR takes a filehandle for the object and returns
the filehandle for the attribute hierarchy. The filehandle for the the filehandle for the attribute hierarchy. The filehandle for the
named attributes is a directory object accessible by LOOKUP or READDIR named attributes is a directory object accessible by LOOKUP or READDIR
and contains files whose names represent the named attributes and and contains files whose names represent the named attributes and
whose data bytes are the value of the attribute. For example: whose data bytes are the value of the attribute. For example:
</t> </t>
<table align="center" anchor="table3"> <table align="center" anchor="table3">
<thead>
<tr>
<th align="left"/>
<th align="left"/>
<th align="left"/>
</tr>
</thead>
<tbody> <tbody>
<tr> <tr>
<td align="left">LOOKUP</td> <td align="left">LOOKUP</td>
<td align="left">"foo"</td> <td align="left">"foo"</td>
<td align="left">; look up file</td> <td align="left">; look up file</td>
</tr> </tr>
<tr> <tr>
<td align="left">GETATTR</td> <td align="left">GETATTR</td>
<td align="left">attrbits</td> <td align="left">attrbits</td>
<td align="left"/> <td align="left"/>
skipping to change at line 7269 skipping to change at line 7144
<td align="left">24</td> <td align="left">24</td>
<td align="left">fs_locations</td> <td align="left">fs_locations</td>
<td align="left">R</td> <td align="left">R</td>
<td align="left"> <td align="left">
<xref target="attrdef_fs_locations" format="default"/> <xref target="attrdef_fs_locations" format="default"/>
</td> </td>
</tr> </tr>
<tr> <tr>
<td align="left">fs_locations_info</td> <td align="left">fs_locations_info</td>
<td align="left">67</td> <td align="left">67</td>
<td align="left">*</td> <td align="left">fs_locations_info4</td>
<td align="left">R</td> <td align="left">R</td>
<td align="left"> <td align="left">
<xref target="attrdef_fs_locations_info" format="default"/> <xref target="attrdef_fs_locations_info" format="default"/>
</td> </td>
</tr> </tr>
<tr> <tr>
<td align="left">fs_status</td> <td align="left">fs_status</td>
<td align="left">61</td> <td align="left">61</td>
<td align="left">fs4_status</td> <td align="left">fs4_status</td>
<td align="left">R</td> <td align="left">R</td>
skipping to change at line 7324 skipping to change at line 7199
<td align="left">uint32_t</td> <td align="left">uint32_t</td>
<td align="left">R</td> <td align="left">R</td>
<td align="left"> <td align="left">
<xref target="attrdef_layout_blksize" format="default"/> <xref target="attrdef_layout_blksize" format="default"/>
</td> </td>
</tr> </tr>
<tr> <tr>
<td align="left">layout_hint</td> <td align="left">layout_hint</td>
<td align="left">63</td> <td align="left">63</td>
<td align="left">layouthint4</td> <td align="left">layouthint4</td>
<td align="left">  W</td> <td align="left">&nbsp;&nbsp;W</td>
<td align="left"> <td align="left">
<xref target="attrdef_layout_hint" format="default"/> <xref target="attrdef_layout_hint" format="default"/>
</td> </td>
</tr> </tr>
<tr> <tr>
<td align="left">layout_type</td> <td align="left">layout_type</td>
<td align="left">64</td> <td align="left">64</td>
<td align="left">layouttype4&lt;&gt;</td> <td align="left">layouttype4&lt;&gt;</td>
<td align="left">R</td> <td align="left">R</td>
<td align="left"> <td align="left">
skipping to change at line 7414 skipping to change at line 7289
<td align="left">mode4</td> <td align="left">mode4</td>
<td align="left">R W</td> <td align="left">R W</td>
<td align="left"> <td align="left">
<xref target="attrdef_mode" format="default"/> <xref target="attrdef_mode" format="default"/>
</td> </td>
</tr> </tr>
<tr> <tr>
<td align="left">mode_set_masked</td> <td align="left">mode_set_masked</td>
<td align="left">74</td> <td align="left">74</td>
<td align="left">mode_masked4</td> <td align="left">mode_masked4</td>
<td align="left">  W</td> <td align="left">&nbsp;&nbsp;W</td>
<td align="left"> <td align="left">
<xref target="attrdef_mode_set_masked" format="default"/> <xref target="attrdef_mode_set_masked" format="default"/>
</td> </td>
</tr> </tr>
<tr> <tr>
<td align="left">mounted_on_fileid</td> <td align="left">mounted_on_fileid</td>
<td align="left">55</td> <td align="left">55</td>
<td align="left">uint64_t</td> <td align="left">uint64_t</td>
<td align="left">R</td> <td align="left">R</td>
<td align="left"> <td align="left">
skipping to change at line 7513 skipping to change at line 7388
<td align="left">retention_get4</td> <td align="left">retention_get4</td>
<td align="left">R</td> <td align="left">R</td>
<td align="left"> <td align="left">
<xref target="attrdef_retentevt_get" format="default"/> <xref target="attrdef_retentevt_get" format="default"/>
</td> </td>
</tr> </tr>
<tr> <tr>
<td align="left">retentevt_set</td> <td align="left">retentevt_set</td>
<td align="left">72</td> <td align="left">72</td>
<td align="left">retention_set4</td> <td align="left">retention_set4</td>
<td align="left">  W</td> <td align="left">&nbsp;&nbsp;W</td>
<td align="left"> <td align="left">
<xref target="attrdef_retentevt_set" format="default"/> <xref target="attrdef_retentevt_set" format="default"/>
</td> </td>
</tr> </tr>
<tr> <tr>
<td align="left">retention_get</td> <td align="left">retention_get</td>
<td align="left">69</td> <td align="left">69</td>
<td align="left">retention_get4</td> <td align="left">retention_get4</td>
<td align="left">R</td> <td align="left">R</td>
<td align="left"> <td align="left">
skipping to change at line 7540 skipping to change at line 7415
<td align="left">uint64_t</td> <td align="left">uint64_t</td>
<td align="left">R W</td> <td align="left">R W</td>
<td align="left"> <td align="left">
<xref target="attrdef_retention_hold" format="default"/> <xref target="attrdef_retention_hold" format="default"/>
</td> </td>
</tr> </tr>
<tr> <tr>
<td align="left">retention_set</td> <td align="left">retention_set</td>
<td align="left">70</td> <td align="left">70</td>
<td align="left">retention_set4</td> <td align="left">retention_set4</td>
<td align="left">  W</td> <td align="left">&nbsp;&nbsp;W</td>
<td align="left"> <td align="left">
<xref target="attrdef_retention_set" format="default"/> <xref target="attrdef_retention_set" format="default"/>
</td> </td>
</tr> </tr>
<tr> <tr>
<td align="left">sacl</td> <td align="left">sacl</td>
<td align="left">59</td> <td align="left">59</td>
<td align="left">nfsacl41</td> <td align="left">nfsacl41</td>
<td align="left">R W</td> <td align="left">R W</td>
<td align="left"> <td align="left">
skipping to change at line 7612 skipping to change at line 7487
<td align="left">nfstime4</td> <td align="left">nfstime4</td>
<td align="left">R</td> <td align="left">R</td>
<td align="left"> <td align="left">
<xref target="attrdef_time_access" format="default"/> <xref target="attrdef_time_access" format="default"/>
</td> </td>
</tr> </tr>
<tr> <tr>
<td align="left">time_access_set</td> <td align="left">time_access_set</td>
<td align="left">48</td> <td align="left">48</td>
<td align="left">settime4</td> <td align="left">settime4</td>
<td align="left">  W</td> <td align="left">&nbsp;&nbsp;W</td>
<td align="left"> <td align="left">
<xref target="attrdef_time_access_set" format="default"/> <xref target="attrdef_time_access_set" format="default"/>
</td> </td>
</tr> </tr>
<tr> <tr>
<td align="left">time_backup</td> <td align="left">time_backup</td>
<td align="left">49</td> <td align="left">49</td>
<td align="left">nfstime4</td> <td align="left">nfstime4</td>
<td align="left">R W</td> <td align="left">R W</td>
<td align="left"> <td align="left">
skipping to change at line 7666 skipping to change at line 7541
<td align="left">nfstime4</td> <td align="left">nfstime4</td>
<td align="left">R</td> <td align="left">R</td>
<td align="left"> <td align="left">
<xref target="attrdef_time_modify" format="default"/> <xref target="attrdef_time_modify" format="default"/>
</td> </td>
</tr> </tr>
<tr> <tr>
<td align="left">time_modify_set</td> <td align="left">time_modify_set</td>
<td align="left">54</td> <td align="left">54</td>
<td align="left">settime4</td> <td align="left">settime4</td>
<td align="left">  W</td> <td align="left">&nbsp;&nbsp;W</td>
<td align="left"> <td align="left">
<xref target="attrdef_time_modify_set" format="default"/> <xref target="attrdef_time_modify_set" format="default"/>
</td> </td>
</tr> </tr>
</tbody> </tbody>
<tfoot>
<tr>
<td align="left" colspan="5">* fs_locations_info4</td>
</tr>
</tfoot>
</table> </table>
</section> </section>
<section anchor="attribute_definitions" numbered="true" toc="default"> <section anchor="attribute_definitions" numbered="true" toc="default">
<name>Attribute Definitions</name> <name>Attribute Definitions</name>
<section anchor="required_attr" numbered="true" toc="default"> <section anchor="required_attr" numbered="true" toc="default">
<name>Definitions of <bcp14>REQUIRED</bcp14> Attributes</name> <name>Definitions of <bcp14>REQUIRED</bcp14> Attributes</name>
<section toc="exclude" anchor="attrdef_supp_attr" numbered="true"> <section toc="exclude" anchor="attrdef_supp_attr" numbered="true">
<name>Attribute 0: supported_attrs</name> <name>Attribute 0: supported_attrs</name>
<t> <t>
The bit vector that would retrieve all <bcp14>REQUIRED</bcp14> and The bit vector that would retrieve all <bcp14>REQUIRED</bcp14> and
skipping to change at line 8529 skipping to change at line 8399
current filehandle refers to a non-pNFS file or directory, the current filehandle refers to a non-pNFS file or directory, the
metadata server should return an attribute that is metadata server should return an attribute that is
representative of the filehandle's file system. It is suggested representative of the filehandle's file system. It is suggested
that this attribute is queried as part of the OPEN operation. that this attribute is queried as part of the OPEN operation.
Due to dynamic system changes, the client should not assume that Due to dynamic system changes, the client should not assume that
the attribute will remain constant for any specific time period; the attribute will remain constant for any specific time period;
thus, it should be periodically refreshed. thus, it should be periodically refreshed.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] "PNFS Attributes" -->
<section anchor="retention" numbered="true" toc="default"> <section anchor="retention" numbered="true" toc="default">
<name>Retention Attributes</name> <name>Retention Attributes</name>
<t> <t>
Retention is a concept whereby a file object can be placed in an Retention is a concept whereby a file object can be placed in an
immutable, undeletable, unrenamable state for a fixed or immutable, undeletable, unrenamable state for a fixed or
infinite duration of time. Once in this "retained" state, the infinite duration of time. Once in this "retained" state, the
file cannot be moved out of the state until the duration of file cannot be moved out of the state until the duration of
retention has been reached. retention has been reached.
</t> </t>
skipping to change at line 8566 skipping to change at line 8435
<t> <t>
If retention is enabled for the associated file, If retention is enabled for the associated file,
this attribute's value represents the retention this attribute's value represents the retention
begin time of the file object. This attribute's begin time of the file object. This attribute's
value is only readable with the GETATTR operation value is only readable with the GETATTR operation
and <bcp14>MUST NOT</bcp14> be modified by the SETATTR operation and <bcp14>MUST NOT</bcp14> be modified by the SETATTR operation
(<xref target="rw_attr" format="default"/>). The value of the (<xref target="rw_attr" format="default"/>). The value of the
attribute consists of: attribute consists of:
</t> </t>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
const RET4_DURATION_INFINITE = 0xffffffffffffffff; const RET4_DURATION_INFINITE = 0xffffffffffffffff;
struct retention_get4 { struct retention_get4 {
uint64_t rg_duration; uint64_t rg_duration;
nfstime4 rg_begin_time<1>; nfstime4 rg_begin_time<1>;
}; };
]]></sourcecode> ]]></sourcecode>
<t> <t>
The field rg_duration is the duration in seconds indicating how The field rg_duration is the duration in seconds indicating how
long the file will be retained once retention is enabled. The long the file will be retained once retention is enabled. The
skipping to change at line 8602 skipping to change at line 8471
This attribute is used to set the retention This attribute is used to set the retention
duration and optionally enable retention for duration and optionally enable retention for
the associated file object. This attribute is the associated file object. This attribute is
only modifiable via the SETATTR operation and only modifiable via the SETATTR operation and
<bcp14>MUST NOT</bcp14> be retrieved by the GETATTR operation <bcp14>MUST NOT</bcp14> be retrieved by the GETATTR operation
(<xref target="rw_attr" format="default"/>). (<xref target="rw_attr" format="default"/>).
This attribute corresponds to retention_get. This attribute corresponds to retention_get.
The value of the attribute consists of: The value of the attribute consists of:
</t> </t>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct retention_set4 { struct retention_set4 {
bool rs_enable; bool rs_enable;
uint64_t rs_duration<1>; uint64_t rs_duration<1>;
}; };
]]></sourcecode> ]]></sourcecode>
<t> <t>
If the client sets rs_enable to TRUE, then it is enabling If the client sets rs_enable to TRUE, then it is enabling
retention on the file object with the begin time of retention retention on the file object with the begin time of retention
starting from the server's current time and date. The starting from the server's current time and date. The
skipping to change at line 8723 skipping to change at line 8592
non-event-based retention. non-event-based retention.
</t> </t>
<t> <t>
If the principal attempting to change retention_hold does If the principal attempting to change retention_hold does
not have ACE4_WRITE_RETENTION_HOLD permissions, not have ACE4_WRITE_RETENTION_HOLD permissions,
the attempt <bcp14>MUST</bcp14> fail with NFS4ERR_ACCESS. the attempt <bcp14>MUST</bcp14> fail with NFS4ERR_ACCESS.
</t> </t>
</section> </section>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- [auth] Copyright (C) The IETF Trust (2007-2008) -->
<!-- [auth] Copyright (C) The Internet Society (2006) -->
<section anchor="acl" numbered="true" toc="default"> <section anchor="acl" numbered="true" toc="default">
<name>Access Control Attributes</name> <name>Access Control Attributes</name>
<t> <t>
Access Control Lists (ACLs) are file attributes that specify Access Control Lists (ACLs) are file attributes that specify
fine-grained access control. This section covers the fine-grained access control. This section covers the
"acl", "dacl", "sacl", "acl", "dacl", "sacl",
"aclsupport", "mode", and "aclsupport", "mode", and
"mode_set_masked" file attributes and their "mode_set_masked" file attributes and their
interactions. Note that file attributes may apply to any file interactions. Note that file attributes may apply to any file
system object. system object.
skipping to change at line 8829 skipping to change at line 8695
Control Entries (ACEs) that are associated with the file Control Entries (ACEs) that are associated with the file
system object. Although the client can set and system object. Although the client can set and
get the acl attribute, the server is responsible for using get the acl attribute, the server is responsible for using
the ACL to perform access control. The client can use the the ACL to perform access control. The client can use the
OPEN or ACCESS operations to check access without modifying OPEN or ACCESS operations to check access without modifying
or reading data or metadata. or reading data or metadata.
</t> </t>
<t> <t>
The NFS ACE structure is defined as follows: The NFS ACE structure is defined as follows:
</t> </t>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
typedef uint32_t acetype4; typedef uint32_t acetype4;
typedef uint32_t aceflag4; typedef uint32_t aceflag4;
typedef uint32_t acemask4; typedef uint32_t acemask4;
struct nfsace4 { struct nfsace4 {
acetype4 type; acetype4 type;
aceflag4 flag; aceflag4 flag;
acemask4 access_mask; acemask4 access_mask;
skipping to change at line 8910 skipping to change at line 8776
The guiding principle with regard to NFSv4 access is The guiding principle with regard to NFSv4 access is
that the server must not accept ACLs that appear to that the server must not accept ACLs that appear to
make access to the file more restrictive than it really is. make access to the file more restrictive than it really is.
</t> </t>
<section numbered="true" toc="default"> <section numbered="true" toc="default">
<name>ACE Type</name> <name>ACE Type</name>
<t> <t>
The constants used for the type field (acetype4) are as The constants used for the type field (acetype4) are as
follows: follows:
</t> </t>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
const ACE4_ACCESS_ALLOWED_ACE_TYPE = 0x00000000; const ACE4_ACCESS_ALLOWED_ACE_TYPE = 0x00000000;
const ACE4_ACCESS_DENIED_ACE_TYPE = 0x00000001; const ACE4_ACCESS_DENIED_ACE_TYPE = 0x00000001;
const ACE4_SYSTEM_AUDIT_ACE_TYPE = 0x00000002; const ACE4_SYSTEM_AUDIT_ACE_TYPE = 0x00000002;
const ACE4_SYSTEM_ALARM_ACE_TYPE = 0x00000003; const ACE4_SYSTEM_ALARM_ACE_TYPE = 0x00000003;
]]></sourcecode> ]]></sourcecode>
<t> <t>
Only the ALLOWED and DENIED bits may be used in the Only the ALLOWED and DENIED bits may be used in the
dacl attribute, and only the AUDIT and ALARM bits may be dacl attribute, and only the AUDIT and ALARM bits may be
used in the sacl attribute. All four are permitted in the used in the sacl attribute. All four are permitted in the
acl attribute. acl attribute.
skipping to change at line 8982 skipping to change at line 8848
</section> </section>
<section anchor="attrdef_aclsupport" numbered="true" toc="default"> <section anchor="attrdef_aclsupport" numbered="true" toc="default">
<name>Attribute 13: aclsupport</name> <name>Attribute 13: aclsupport</name>
<t> <t>
A server need not support all of the above ACE types. A server need not support all of the above ACE types.
This attribute indicates which ACE types are supported for This attribute indicates which ACE types are supported for
the current file system. The bitmask constants used to the current file system. The bitmask constants used to
represent the above definitions within the aclsupport represent the above definitions within the aclsupport
attribute are as follows: attribute are as follows:
</t> </t>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
const ACL4_SUPPORT_ALLOW_ACL = 0x00000001; const ACL4_SUPPORT_ALLOW_ACL = 0x00000001;
const ACL4_SUPPORT_DENY_ACL = 0x00000002; const ACL4_SUPPORT_DENY_ACL = 0x00000002;
const ACL4_SUPPORT_AUDIT_ACL = 0x00000004; const ACL4_SUPPORT_AUDIT_ACL = 0x00000004;
const ACL4_SUPPORT_ALARM_ACL = 0x00000008; const ACL4_SUPPORT_ALARM_ACL = 0x00000008;
]]></sourcecode> ]]></sourcecode>
<t> <t>
Servers that support either the ALLOW or DENY ACE type Servers that support either the ALLOW or DENY ACE type
<bcp14>SHOULD</bcp14> support both ALLOW and DENY ACE types. <bcp14>SHOULD</bcp14> support both ALLOW and DENY ACE types.
</t> </t>
<t> <t>
skipping to change at line 9019 skipping to change at line 8885
if it supports AUDIT or ALARM ACEs, then it <bcp14>MUST</bcp14> support if it supports AUDIT or ALARM ACEs, then it <bcp14>MUST</bcp14> support
the sacl attribute. the sacl attribute.
</t> </t>
</section> </section>
<section anchor="acemask" numbered="true" toc="default"> <section anchor="acemask" numbered="true" toc="default">
<name>ACE Access Mask</name> <name>ACE Access Mask</name>
<t> <t>
The bitmask constants used for the access mask field The bitmask constants used for the access mask field
are as follows: are as follows:
</t> </t>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
const ACE4_READ_DATA = 0x00000001; const ACE4_READ_DATA = 0x00000001;
const ACE4_LIST_DIRECTORY = 0x00000001; const ACE4_LIST_DIRECTORY = 0x00000001;
const ACE4_WRITE_DATA = 0x00000002; const ACE4_WRITE_DATA = 0x00000002;
const ACE4_ADD_FILE = 0x00000002; const ACE4_ADD_FILE = 0x00000002;
const ACE4_APPEND_DATA = 0x00000004; const ACE4_APPEND_DATA = 0x00000004;
const ACE4_ADD_SUBDIRECTORY = 0x00000004; const ACE4_ADD_SUBDIRECTORY = 0x00000004;
const ACE4_READ_NAMED_ATTRS = 0x00000008; const ACE4_READ_NAMED_ATTRS = 0x00000008;
const ACE4_WRITE_NAMED_ATTRS = 0x00000010; const ACE4_WRITE_NAMED_ATTRS = 0x00000010;
const ACE4_EXECUTE = 0x00000020; const ACE4_EXECUTE = 0x00000020;
const ACE4_DELETE_CHILD = 0x00000040; const ACE4_DELETE_CHILD = 0x00000040;
skipping to change at line 9541 skipping to change at line 9407
taking the place of the write bit. taking the place of the write bit.
</t> </t>
</section> </section>
</section> </section>
<section anchor="aceflag" numbered="true" toc="default"> <section anchor="aceflag" numbered="true" toc="default">
<name>ACE flag</name> <name>ACE flag</name>
<t> <t>
The bitmask constants used for the flag field are as The bitmask constants used for the flag field are as
follows: follows:
</t> </t>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
const ACE4_FILE_INHERIT_ACE = 0x00000001; const ACE4_FILE_INHERIT_ACE = 0x00000001;
const ACE4_DIRECTORY_INHERIT_ACE = 0x00000002; const ACE4_DIRECTORY_INHERIT_ACE = 0x00000002;
const ACE4_NO_PROPAGATE_INHERIT_ACE = 0x00000004; const ACE4_NO_PROPAGATE_INHERIT_ACE = 0x00000004;
const ACE4_INHERIT_ONLY_ACE = 0x00000008; const ACE4_INHERIT_ONLY_ACE = 0x00000008;
const ACE4_SUCCESSFUL_ACCESS_ACE_FLAG = 0x00000010; const ACE4_SUCCESSFUL_ACCESS_ACE_FLAG = 0x00000010;
const ACE4_FAILED_ACCESS_ACE_FLAG = 0x00000020; const ACE4_FAILED_ACCESS_ACE_FLAG = 0x00000020;
const ACE4_IDENTIFIER_GROUP = 0x00000040; const ACE4_IDENTIFIER_GROUP = 0x00000040;
const ACE4_INHERITED_ACE = 0x00000080; const ACE4_INHERITED_ACE = 0x00000080;
]]></sourcecode> ]]></sourcecode>
<t> <t>
skipping to change at line 9629 skipping to change at line 9495
<t> <t>
If this flag is present on an ACE, but If this flag is present on an ACE, but
neither ACE4_DIRECTORY_INHERIT_ACE nor neither ACE4_DIRECTORY_INHERIT_ACE nor
ACE4_FILE_INHERIT_ACE is present, then ACE4_FILE_INHERIT_ACE is present, then
an operation attempting to set such an an operation attempting to set such an
attribute <bcp14>SHOULD</bcp14> fail with attribute <bcp14>SHOULD</bcp14> fail with
NFS4ERR_ATTRNOTSUPP. NFS4ERR_ATTRNOTSUPP.
</t> </t>
</dd> </dd>
<dt>ACE4_SUCCESSFUL_ACCESS_ACE_FLAG</dt> <dt>ACE4_SUCCESSFUL_ACCESS_ACE_FLAG and
<dd/> ACE4_FAILED_ACCESS_ACE_FLAG</dt>
<dt>ACE4_FAILED_ACCESS_ACE_FLAG</dt> <dd>
<dd> <t>
The ACE4_SUCCESSFUL_ACCESS_ACE_FLAG The ACE4_SUCCESSFUL_ACCESS_ACE_FLAG
(SUCCESS) and ACE4_FAILED_ACCESS_ACE_FLAG (SUCCESS) and ACE4_FAILED_ACCESS_ACE_FLAG
(FAILED) flag bits may be set only on (FAILED) flag bits may be set only on
ACE4_SYSTEM_AUDIT_ACE_TYPE (AUDIT) and ACE4_SYSTEM_AUDIT_ACE_TYPE (AUDIT) and
ACE4_SYSTEM_ALARM_ACE_TYPE (ALARM) ACE ACE4_SYSTEM_ALARM_ACE_TYPE (ALARM) ACE
types. If during the processing of the types. If during the processing of the
file's ACL, the server encounters an AUDIT file's ACL, the server encounters an AUDIT
or ALARM ACE that matches the principal or ALARM ACE that matches the principal
attempting the OPEN, the server notes that attempting the OPEN, the server notes that
fact, and the presence, if any, of the fact, and the presence, if any, of the
skipping to change at line 9658 skipping to change at line 9524
the SUCCESS flag was set for a matching the SUCCESS flag was set for a matching
AUDIT or ALARM ACE, then the appropriate AUDIT or ALARM ACE, then the appropriate
AUDIT or ALARM event occurs. If the AUDIT or ALARM event occurs. If the
operation failed, and if the FAILED flag operation failed, and if the FAILED flag
was set for the matching AUDIT or ALARM was set for the matching AUDIT or ALARM
ACE, then the appropriate AUDIT or ALARM ACE, then the appropriate AUDIT or ALARM
event occurs. Either or both of the event occurs. Either or both of the
SUCCESS or FAILED can be set, but if SUCCESS or FAILED can be set, but if
neither is set, the AUDIT or ALARM ACE is neither is set, the AUDIT or ALARM ACE is
not useful. not useful.
</dd> </t>
<dt/> <t>
<dd>
The previously described processing The previously described processing
applies to ACCESS operations even when applies to ACCESS operations even when
they return NFS4_OK. For the purposes of they return NFS4_OK. For the purposes of
AUDIT and ALARM, we consider an ACCESS AUDIT and ALARM, we consider an ACCESS
operation to be a "failure" if it fails operation to be a "failure" if it fails
to return a bit that was requested and to return a bit that was requested and
supported. supported.</t>
</dd> </dd>
<dt>ACE4_IDENTIFIER_GROUP</dt> <dt>ACE4_IDENTIFIER_GROUP</dt>
<dd> <dd>
Indicates that the "who" refers to a GROUP Indicates that the "who" refers to a GROUP
as defined under UNIX or a GROUP ACCOUNT as defined under UNIX or a GROUP ACCOUNT
as defined under Windows. Clients and as defined under Windows. Clients and
servers <bcp14>MUST</bcp14> ignore the servers <bcp14>MUST</bcp14> ignore the
ACE4_IDENTIFIER_GROUP flag on ACEs with a ACE4_IDENTIFIER_GROUP flag on ACEs with a
who value equal to one of the special who value equal to one of the special
identifiers outlined in identifiers outlined in
skipping to change at line 9836 skipping to change at line 9701
attribute supports automatic inheritance (see attribute supports automatic inheritance (see
<xref target="auto_inherit" format="default"/>). <xref target="auto_inherit" format="default"/>).
</t> </t>
</section> </section>
<section anchor="attrdef_mode" numbered="true" toc="default"> <section anchor="attrdef_mode" numbered="true" toc="default">
<name>Attribute 33: mode</name> <name>Attribute 33: mode</name>
<t> <t>
The NFSv4.1 mode attribute is based on the UNIX mode The NFSv4.1 mode attribute is based on the UNIX mode
bits. The following bits are defined: bits. The following bits are defined:
</t> </t>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
const MODE4_SUID = 0x800; /* set user id on execution */ const MODE4_SUID = 0x800; /* set user id on execution */
const MODE4_SGID = 0x400; /* set group id on execution */ const MODE4_SGID = 0x400; /* set group id on execution */
const MODE4_SVTX = 0x200; /* save text even after use */ const MODE4_SVTX = 0x200; /* save text even after use */
const MODE4_RUSR = 0x100; /* read permission: owner */ const MODE4_RUSR = 0x100; /* read permission: owner */
const MODE4_WUSR = 0x080; /* write permission: owner */ const MODE4_WUSR = 0x080; /* write permission: owner */
const MODE4_XUSR = 0x040; /* execute permission: owner */ const MODE4_XUSR = 0x040; /* execute permission: owner */
const MODE4_RGRP = 0x020; /* read permission: group */ const MODE4_RGRP = 0x020; /* read permission: group */
const MODE4_WGRP = 0x010; /* write permission: group */ const MODE4_WGRP = 0x010; /* write permission: group */
const MODE4_XGRP = 0x008; /* execute permission: group */ const MODE4_XGRP = 0x008; /* execute permission: group */
const MODE4_ROTH = 0x004; /* read permission: other */ const MODE4_ROTH = 0x004; /* read permission: other */
skipping to change at line 10339 skipping to change at line 10204
</section> </section>
<section anchor="auto_inherit" numbered="true" toc="default"> <section anchor="auto_inherit" numbered="true" toc="default">
<name>Automatic Inheritance</name> <name>Automatic Inheritance</name>
<t> <t>
The acl attribute consists only of an array of ACEs, but The acl attribute consists only of an array of ACEs, but
the <xref target="attrdef_sacl" format="default">sacl</xref> the <xref target="attrdef_sacl" format="default">sacl</xref>
and <xref target="attrdef_dacl" format="default">dacl</xref> attributes and <xref target="attrdef_dacl" format="default">dacl</xref> attributes
also include an additional flag field. also include an additional flag field.
</t> </t>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct nfsacl41 { struct nfsacl41 {
aclflag4 na41_flag; aclflag4 na41_flag;
nfsace4 na41_aces<>; nfsace4 na41_aces<>;
}; };
]]></sourcecode> ]]></sourcecode>
<t> <t>
The flag field The flag field
applies to the entire sacl or dacl; three flag values are applies to the entire sacl or dacl; three flag values are
defined: defined:
</t> </t>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
const ACL4_AUTO_INHERIT = 0x00000001; const ACL4_AUTO_INHERIT = 0x00000001;
const ACL4_PROTECTED = 0x00000002; const ACL4_PROTECTED = 0x00000002;
const ACL4_DEFAULTED = 0x00000004; const ACL4_DEFAULTED = 0x00000004;
]]></sourcecode> ]]></sourcecode>
<t> <t>
and all other bits must be cleared. The and all other bits must be cleared. The
ACE4_INHERITED_ACE flag may be set in the ACEs of the sacl ACE4_INHERITED_ACE flag may be set in the ACEs of the sacl
or dacl (whereas it must always be cleared in the acl). or dacl (whereas it must always be cleared in the acl).
</t> </t>
skipping to change at line 10476 skipping to change at line 10341
<bcp14>SHOULD</bcp14> set the ACL4_DEFAULTED flag on the ACL it chooses for <bcp14>SHOULD</bcp14> set the ACL4_DEFAULTED flag on the ACL it chooses for
the new object. An application performing automatic the new object. An application performing automatic
inheritance takes the ACL4_DEFAULTED flag as a sign that the inheritance takes the ACL4_DEFAULTED flag as a sign that the
ACL should be completely replaced by one generated using the ACL should be completely replaced by one generated using the
automatic inheritance rules. automatic inheritance rules.
</t> </t>
</section> </section>
</section> </section>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- [auth] Copyright (C) The IETF Trust (2007) -->
<!-- [auth] Copyright (C) The Internet Society (2006) -->
<section anchor="single_server_namespace" numbered="true" toc="default"> <section anchor="single_server_namespace" numbered="true" toc="default">
<name>Single-Server Namespace</name> <name>Single-Server Namespace</name>
<t> <t>
This section describes the NFSv4 single-server namespace. This section describes the NFSv4 single-server namespace.
Single-server namespaces may be presented directly to clients, Single-server namespaces may be presented directly to clients,
or they may be used as a basis to form larger multi-server or they may be used as a basis to form larger multi-server
namespaces (e.g., site-wide or organization-wide) to be presented namespaces (e.g., site-wide or organization-wide) to be presented
to clients, as described in <xref target="NEW11" format="default"/>. to clients, as described in <xref target="NEW11" format="default"/>.
</t> </t>
<section anchor="server_exports" numbered="true" toc="default"> <section anchor="server_exports" numbered="true" toc="default">
skipping to change at line 10719 skipping to change at line 10581
entire the pseudo file system accessible by all of the valid security entire the pseudo file system accessible by all of the valid security
mechanisms. mechanisms.
</t> </t>
<t> <t>
Where there is concern about the security of data on the network, Where there is concern about the security of data on the network,
clients should use strong security mechanisms to access the pseudo clients should use strong security mechanisms to access the pseudo
file system in order to prevent man-in-the-middle attacks. file system in order to prevent man-in-the-middle attacks.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- [auth] Copyright (C) The IETF Trust (2007-2008) -->
<!-- [auth] Copyright (C) The Internet Society (2006) -->
<section numbered="true" toc="default"> <section numbered="true" toc="default">
<name>State Management</name> <name>State Management</name>
<t> <t>
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 such features as share reservations, stateful. With the inclusion of such features as share reservations,
file and directory delegations, recallable layouts, and support for file and directory delegations, recallable layouts, and support for
mandatory byte-range locking, the protocol becomes substantially more mandatory byte-range locking, the protocol becomes substantially more
dependent on proper management of state than the traditional dependent on proper management of state than the traditional
combination of NFS and NLM (Network Lock Manager) combination of NFS and NLM (Network Lock Manager)
<xref target="xnfs" format="default"/>. These features include expanded <xref target="xnfs" format="default"/>. These features include expanded
skipping to change at line 10792 skipping to change at line 10651
<t> <t>
For some types of locking interactions, the client will represent For some types of locking interactions, the client will represent
some number of internal locking entities called "owners", which some number of internal locking entities called "owners", which
normally correspond to processes internal to the client. For normally correspond to processes internal to the client. For
other types of locking-related objects, such as delegations and other types of locking-related objects, such as delegations and
layouts, no such intermediate entities are provided for, and the layouts, no such intermediate entities are provided for, and the
locking-related objects are considered to be transferred locking-related objects are considered to be transferred
directly between the server and a unitary client. directly between the server and a unitary client.
</t> </t>
</section> </section>
<!-- [auth] "Client and Session ID" -->
<section anchor="stateid" numbered="true" toc="default"> <section anchor="stateid" numbered="true" toc="default">
<name>Stateid Definition</name> <name>Stateid Definition</name>
<t> <t>
When the server grants a lock of any type (including opens, When the server grants a lock of any type (including opens,
byte-range locks, delegations, and layouts), it responds with a byte-range locks, delegations, and layouts), it responds with a
unique stateid that represents a set of locks (often a single unique stateid that represents a set of locks (often a single
lock) for the same file, of the same type, and sharing the same lock) for the same file, of the same type, and sharing the same
ownership characteristics. Thus, opens of the same file by ownership characteristics. Thus, opens of the same file by
different open-owners each have an identifying stateid. Similarly, different open-owners each have an identifying stateid. Similarly,
each set of byte-range locks on a file owned by a specific lock-owner each set of byte-range locks on a file owned by a specific lock-owner
skipping to change at line 11007 skipping to change at line 10865
into account. When two seqid values are being compared, into account. When two seqid values are being compared,
the total count of slots for all sessions associated the total count of slots for all sessions associated
with the current client is used to do this. When one with the current client is used to do this. When one
seqid value is less than this total slot count and seqid value is less than this total slot count and
another seqid value is greater than NFS4_UINT32_MAX another seqid value is greater than NFS4_UINT32_MAX
minus the total slot count, the former is to be treated minus the total slot count, the former is to be treated
as lower than the latter, despite the fact that it is as lower than the latter, despite the fact that it is
numerically greater. numerically greater.
</t> </t>
</section> </section>
<!-- [auth] "Stateid Structure" -->
<section anchor="special_stateid" numbered="true" toc="default"> <section anchor="special_stateid" numbered="true" toc="default">
<name>Special Stateids</name> <name>Special Stateids</name>
<t> <t>
Stateid values whose "other" field is either all zeros or all Stateid values whose "other" field is either all zeros or all
ones are reserved. They may not be assigned by the server but ones are reserved. They may not be assigned by the server but
have special meanings defined by the protocol. The particular have special meanings defined by the protocol. The particular
meaning depends on whether the "other" field is all zeros or meaning depends on whether the "other" field is all zeros or
all ones and the specific value of the "seqid" field. all ones and the specific value of the "seqid" field.
</t> </t>
<t> <t>
skipping to change at line 11091 skipping to change at line 10948
individual client IDs or filehandles and can be used with all valid individual client IDs or filehandles and can be used with all valid
client IDs and filehandles. In the case of a special client IDs and filehandles. In the case of a special
stateid designating the current stateid, the current stateid stateid designating the current stateid, the current stateid
value substituted for the special stateid is associated with a value substituted for the special stateid is associated with a
particular client ID and filehandle, and so, if it is used particular client ID and filehandle, and so, if it is used
where the current filehandle does not match that associated with the current where the current filehandle does not match that associated with the current
stateid, the operation to which the stateid is passed will return stateid, the operation to which the stateid is passed will return
NFS4ERR_BAD_STATEID. NFS4ERR_BAD_STATEID.
</t> </t>
</section> </section>
<!-- [auth] "Special Stateids" -->
<section anchor="stateid_lifetime" numbered="true" toc="default"> <section anchor="stateid_lifetime" numbered="true" toc="default">
<name>Stateid Lifetime and Validation</name> <name>Stateid Lifetime and Validation</name>
<t> <t>
Stateids must remain valid until either a client restart or a Stateids must remain valid until either a client restart or a
server restart or until the client returns all of the locks server restart or until the client returns all of the locks
associated with the stateid by means of an operation such as associated with the stateid by means of an operation such as
CLOSE or DELEGRETURN. CLOSE or DELEGRETURN.
If the locks are lost due to revocation, as long If the locks are lost due to revocation, as long
as the client ID is valid, the stateid remains as the client ID is valid, the stateid remains
skipping to change at line 11294 skipping to change at line 11150
Otherwise, the stateid is valid and the table entry Otherwise, the stateid is valid and the table entry
should contain any additional information about the should contain any additional information about the
type of stateid and information associated with that type of stateid and information associated with that
particular type of stateid, such as the associated particular type of stateid, such as the associated
set of locks, e.g., open-owner and set of locks, e.g., open-owner and
lock-owner information, as well as information on the lock-owner information, as well as information on the
specific locks, e.g., open modes and byte-ranges. specific locks, e.g., open modes and byte-ranges.
</li> </li>
</ul> </ul>
</section> </section>
<!-- [auth] "Stateid Lifetime and Validation" -->
<section anchor="stateid_use" numbered="true" toc="default"> <section anchor="stateid_use" numbered="true" toc="default">
<name>Stateid Use for I/O Operations</name> <name>Stateid Use for I/O Operations</name>
<t> <t>
Clients performing I/O operations need to select an Clients performing I/O operations need to select an
appropriate stateid based on the appropriate stateid based on the
locks (including opens and delegations) held by the client and locks (including opens and delegations) held by the client and
the various types of state-owners sending the I/O requests. the various types of state-owners sending the I/O requests.
SETATTR operations that change the file size are treated SETATTR operations that change the file size are treated
like I/O operations in this regard. like I/O operations in this regard.
</t> </t>
skipping to change at line 11350 skipping to change at line 11205
a request might be avoidably rejected. a request might be avoidably rejected.
</t> </t>
<t> <t>
The server however should not try to enforce these ordering rules The server however should not try to enforce these ordering rules
and should use whatever information is available to properly process and should use whatever information is available to properly process
I/O requests. In particular, when a client has a delegation for a given file, it I/O requests. In particular, when a client has a delegation for a given file, it
<bcp14>SHOULD</bcp14> take note of this fact in processing a request, even if it is <bcp14>SHOULD</bcp14> take note of this fact in processing a request, even if it is
sent with a special stateid. sent with a special stateid.
</t> </t>
</section> </section>
<!-- [auth] "Stateid Use for I/O Operations" -->
<section anchor="stateid_use_sa" numbered="true" toc="default"> <section anchor="stateid_use_sa" numbered="true" toc="default">
<name>Stateid Use for SETATTR Operations</name> <name>Stateid Use for SETATTR Operations</name>
<t> <t>
Because each operation is associated with a session ID and from that Because each operation is associated with a session ID and from that
the clientid can be determined, operations do not need to the clientid can be determined, operations do not need to
include a stateid for the server to be able to determine whether include a stateid for the server to be able to determine whether
they should cause a delegation to be recalled or are to be they should cause a delegation to be recalled or are to be
treated as done within the scope of the delegation. treated as done within the scope of the delegation.
</t> </t>
<t> <t>
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 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 a special stateid or, when a delegation is held for the file in
question, a delegation stateid. While the server <bcp14>SHOULD</bcp14> validate question, a delegation stateid. While the server <bcp14>SHOULD</bcp14> validate
the stateid and may use the stateid to optimize the determination the stateid and may use the stateid to optimize the determination
as to whether a delegation is held, it <bcp14>SHOULD</bcp14> note the presence of as to whether a delegation is held, it <bcp14>SHOULD</bcp14> note the presence of
a delegation even when a special stateid is sent, and <bcp14>MUST</bcp14> accept a a delegation even when a special stateid is sent, and <bcp14>MUST</bcp14> accept a
valid delegation stateid when sent. valid delegation stateid when sent.
</t> </t>
</section> </section>
<!-- [auth] "Stateid Use for SETATTR Operations" -->
</section> </section>
<!-- [auth] "Stateid Definition" -->
<section anchor="lease_renewal" numbered="true" toc="default"> <section anchor="lease_renewal" numbered="true" toc="default">
<name>Lease Renewal</name> <name>Lease Renewal</name>
<t> <t>
Each client/server pair, as represented by a client ID, has a single Each client/server pair, as represented by a client ID, has a single
lease. lease.
The purpose of the lease is to allow the client to indicate The purpose of the lease is to allow the client to indicate
to the server, in a low-overhead way, that it is active, and to the server, in a low-overhead way, that it is active, and
thus that the server is to retain the client's locks. This arrangement thus that the server is to retain the client's locks. This arrangement
allows the server to remove stale locking-related objects allows the server to remove stale locking-related objects
that are held by a client that has crashed or is otherwise that are held by a client that has crashed or is otherwise
skipping to change at line 11541 skipping to change at line 11393
restart the client must reclaim locking state. restart the client must reclaim locking state.
</li> </li>
<li> <li>
The status bit SEQ4_STATUS_BACKCHANNEL_FAULT The status bit SEQ4_STATUS_BACKCHANNEL_FAULT
indicates that the server has encountered an unrecoverable fault indicates that the server has encountered an unrecoverable fault
with the backchannel (e.g., it has lost track of a with the backchannel (e.g., it has lost track of a
sequence ID for a slot in the backchannel). sequence ID for a slot in the backchannel).
</li> </li>
</ul> </ul>
</section> </section>
<!-- [auth] "Lease Renewal" -->
<section anchor="lock_crash_recovery" numbered="true" toc="default"> <section anchor="lock_crash_recovery" numbered="true" toc="default">
<name>Crash Recovery</name> <name>Crash Recovery</name>
<t> <t>
A critical requirement in crash recovery is that both the client A critical requirement in crash recovery is that both the client
and the server know when the other has failed. Additionally, it and the server know when the other has failed. Additionally, it
is required that a client sees a consistent view of data across is required that a client sees a consistent view of data across
server restarts. All READ and WRITE operations that server restarts. All READ and WRITE operations that
may have been queued within the client or network buffers must may have been queued within the client or network buffers must
wait until the client has successfully recovered the locks wait until the client has successfully recovered the locks
protecting the READ and WRITE operations. Any that reach the protecting the READ and WRITE operations. Any that reach the
skipping to change at line 11612 skipping to change at line 11463
derived from the old verifier. At this point, conflicting locks from derived from the old verifier. At this point, conflicting locks from
other clients, kept waiting while the lease had not yet expired, can other clients, kept waiting while the lease had not yet expired, can
be granted. In addition, all stateids associated with the old client ID be granted. In addition, all stateids associated with the old client ID
can also be freed, as they are no longer reference-able. can also be freed, as they are no longer reference-able.
</t> </t>
<t> <t>
Note that the verifier must have the same uniqueness properties as the Note that the verifier must have the same uniqueness properties as the
verifier for the COMMIT operation. verifier for the COMMIT operation.
</t> </t>
</section> </section>
<!-- [auth] "Client Failure and Recovery" -->
<section anchor="server_failure" numbered="true" toc="default"> <section anchor="server_failure" numbered="true" toc="default">
<name>Server Failure and Recovery</name> <name>Server Failure and Recovery</name>
<t> <t>
If the server loses locking state (usually as a result of a restart), it must allow clients time to discover this fact and If the server loses locking state (usually as a result of a restart), it must allow clients time to discover this fact and
re-establish the lost locking state. The client must be able to re-establish the lost locking state. The client must be able to
re-establish the locking state without having the server deny valid re-establish the locking state without having the server deny valid
requests because the server has granted conflicting access to another requests because the server has granted conflicting access to another
client. Likewise, if there is a possibility that clients have not client. Likewise, if there is a possibility that clients have not
yet re-established their locking state for a file and that yet re-established their locking state for a file and that
such locking state might make it invalid to perform READ or such locking state might make it invalid to perform READ or
skipping to change at line 11921 skipping to change at line 11771
IDs with the EXCHGID4_FLAG_BIND_PRINC_STATEID (<xref target="OP_EXCHANGE_ID" format="default"/>) capability set, then the server IDs with the EXCHGID4_FLAG_BIND_PRINC_STATEID (<xref target="OP_EXCHANGE_ID" format="default"/>) capability set, then the server
<bcp14>SHOULD</bcp14> record in stable storage the client owner and the <bcp14>SHOULD</bcp14> record in stable storage the client owner and the
principal that established the client ID via EXCHANGE_ID. principal that established the client ID via EXCHANGE_ID.
If the server does not, then there is a risk a client will If the server does not, then there is a risk a client will
be unable to reclaim state if it does not have a credential be unable to reclaim state if it does not have a credential
for a principal that was originally authorized to for a principal that was originally authorized to
establish the state. establish the state.
</t> </t>
</section> </section>
<!-- [auth] "Security Considerations for State Reclaim" -->
</section> </section>
<!-- [auth] "State Reclaim" -->
</section> </section>
<!-- [auth] "Server Failure and Recovery" -->
<section anchor="network_partitions_and_recovery" numbered="true" toc="default"> <section anchor="network_partitions_and_recovery" numbered="true" toc="default">
<name>Network Partitions and Recovery</name> <name>Network Partitions and Recovery</name>
<t> <t>
If the duration of a network partition is greater than the lease If the duration of a network partition is greater than the lease
period provided by the server, the server will not have received a period provided by the server, the server will not have received a
lease renewal from the client. If this occurs, the server may free lease renewal from the client. If this occurs, the server may free
all locks held for the client or it may allow the lock state to all locks held for the client or it may allow the lock state to
remain for a considerable period, subject to the constraint that remain for a considerable period, subject to the constraint that
if a request for a conflicting lock is made, locks associated with if a request for a conflicting lock is made, locks associated with
an expired lease do not prevent such a conflicting lock from being an expired lease do not prevent such a conflicting lock from being
skipping to change at line 12217 skipping to change at line 12064
as via a UNIX signal, a Graphical User Interface (GUI) pop-up window, etc. as via a UNIX signal, a Graphical User Interface (GUI) pop-up window, etc.
See <xref target="data_caching_revocation" format="default"/> See <xref target="data_caching_revocation" format="default"/>
for a discussion of what the client should do for a discussion of what the client should do
for dealing with unreclaimed delegations on client state. for dealing with unreclaimed delegations on client state.
</t> </t>
<t> <t>
For further discussion of revocation of locks, see For further discussion of revocation of locks, see
<xref target="server_revocation" format="default"/>. <xref target="server_revocation" format="default"/>.
</t> </t>
</section> </section>
<!-- [auth] "Network Partitions and Recovery" -->
</section> </section>
<!-- [auth] "Crash Recovery" -->
<section anchor="server_revocation" numbered="true" toc="default"> <section anchor="server_revocation" numbered="true" toc="default">
<name>Server Revocation of Locks</name> <name>Server Revocation of Locks</name>
<t> <t>
At any point, the server can revoke locks held by a client, and the At any point, the server can revoke locks held by a client, and the
client must be prepared for this event. When the client detects that client must be prepared for this event. When the client detects that
its locks have been or may have been revoked, the client is its locks have been or may have been revoked, the client is
responsible for validating the state information between itself and responsible for validating the state information between itself and
the server. Validating locking state for the client means that it the server. Validating locking state for the client means that it
must verify or reclaim state for each lock currently held. must verify or reclaim state for each lock currently held.
</t> </t>
skipping to change at line 12279 skipping to change at line 12124
In all situations in which a subset of locking state may have been In all situations in which a subset of locking state may have been
revoked, which include all cases in which locking state is revoked revoked, which include all cases in which locking state is revoked
within the lease period, it is up to the client to determine which within the lease period, it is up to the client to determine which
locks have been revoked and which have not. It does this by locks have been revoked and which have not. It does this by
using the TEST_STATEID operation on the appropriate set of stateids. using the TEST_STATEID operation on the appropriate set of stateids.
Once the set of revoked locks has been determined, the applications Once the set of revoked locks has been determined, the applications
can be notified, and the invalidated stateids can be freed and can be notified, and the invalidated stateids can be freed and
lock revocation acknowledged by using FREE_STATEID. lock revocation acknowledged by using FREE_STATEID.
</t> </t>
</section> </section>
<!-- [auth] "Server Revocation of Locks" -->
<section numbered="true" toc="default"> <section numbered="true" toc="default">
<name>Short and Long Leases</name> <name>Short and Long Leases</name>
<t> <t>
When determining the time period for the server lease, the usual lease When determining the time period for the server lease, the usual lease
trade-offs apply. A short lease is good for fast server recovery at a trade-offs apply. A short lease is good for fast server recovery at a
cost of increased operations to effect lease renewal (when there are cost of increased operations to effect lease renewal (when there are
no other operations during the period to effect lease renewal as a no other operations during the period to effect lease renewal as a
side effect). A long lease is certainly kinder and gentler to side effect). A long lease is certainly kinder and gentler to
servers trying to handle very large numbers of clients. The number of extra requests servers trying to handle very large numbers of clients. The number of extra requests
to effect lock renewal drops in inverse to effect lock renewal drops in inverse
skipping to change at line 12305 skipping to change at line 12149
the longer period for a lease to expire will force conflicting the longer period for a lease to expire will force conflicting
requests to wait longer. requests to wait longer.
</t> </t>
<t> <t>
A long lease is practical if the server can store lease state in A long lease is practical if the server can store lease state in
stable storage. Upon recovery, the server can reconstruct the stable storage. Upon recovery, the server can reconstruct the
lease state from its stable storage and continue operation with lease state from its stable storage and continue operation with
its clients. its clients.
</t> </t>
</section> </section>
<!-- [auth] "Short and Long Leases" -->
<section anchor="lease_propagation_delay" numbered="true" toc="default"> <section anchor="lease_propagation_delay" numbered="true" toc="default">
<name>Clocks, Propagation Delay, and Calculating Lease Expiration</name> <name>Clocks, Propagation Delay, and Calculating Lease Expiration</name>
<t> <t>
To avoid the need for synchronized clocks, lease times are granted by To avoid the need for synchronized clocks, lease times are granted by
the server as a time delta. However, there is a requirement that the the server as a time delta. However, there is a requirement that the
client and server clocks do not drift excessively over the duration of client and server clocks do not drift excessively over the duration of
the lease. There is also the issue of propagation delay across the the lease. There is also the issue of propagation delay across the
network, which could easily be several hundred milliseconds, as well as network, which could easily be several hundred milliseconds, as well as
the possibility that requests will be lost and need to be the possibility that requests will be lost and need to be
retransmitted. retransmitted.
skipping to change at line 12341 skipping to change at line 12184
The server's lease period configuration should take into account the The server's lease period configuration should take into account the
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 factors account the network propagation delays and other network delay factors
for the client population. Since the protocol does not allow for an for the client population. Since the protocol does not allow for an
automatic method to determine an appropriate lease period, the 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.
</t> </t>
</section> </section>
<!-- [auth] "Clocks, Propagation Delay, and Calculating Lease Expiration" -->
<section anchor="vestigial_locking" numbered="true" toc="default"> <section anchor="vestigial_locking" numbered="true" toc="default">
<name>Obsolete Locking Infrastructure from NFSv4.0</name> <name>Obsolete Locking Infrastructure from NFSv4.0</name>
<t> <t>
There are a number of operations and fields within existing There are a number of operations and fields within existing
operations that no longer have a function in NFSv4.1. operations that no longer have a function in NFSv4.1.
In one way or another, these changes are all due to In one way or another, these changes are all due to
the implementation of sessions that provide client context the implementation of sessions that provide client context
and exactly once semantics as a base feature of the protocol, and exactly once semantics as a base feature of the protocol,
separate from locking itself. separate from locking itself.
</t> </t>
skipping to change at line 12408 skipping to change at line 12250
client ID field. client ID field.
</li> </li>
</ul> </ul>
<t> <t>
Such vestigial fields in existing operations have no function in Such vestigial fields in existing operations have no function in
NFSv4.1 and are ignored by the server. Note that client IDs in NFSv4.1 and are ignored by the server. Note that client IDs in
operations new to NFSv4.1 (such as CREATE_SESSION and DESTROY_CLIENTID) operations new to NFSv4.1 (such as CREATE_SESSION and DESTROY_CLIENTID)
are not ignored. are not ignored.
</t> </t>
</section> </section>
<!-- [auth] "Vestigial Locking Infrastructure From V4.0" -->
</section> </section>
<!-- [auth] "State Management" -->
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- [auth] Copyright (C) The IETF Trust (2007-2008) -->
<!-- [auth] Copyright (C) The Internet Society (2006) -->
<section anchor="file_locking" numbered="true" toc="default"> <section anchor="file_locking" numbered="true" toc="default">
<name>File Locking and Share Reservations</name> <name>File Locking and Share Reservations</name>
<t> <t>
To support Win32 share reservations, it is necessary to provide To support Win32 share reservations, it is necessary to provide
operations that atomically open or create files. Having a operations that atomically open or create files. Having a
separate share/unshare operation would not allow correct separate share/unshare operation would not allow correct
implementation of the Win32 OpenFile API. In order to implementation of the Win32 OpenFile API. In order to
correctly implement share semantics, the previous NFS protocol correctly implement share semantics, the previous NFS protocol
mechanisms used when a file is opened or created (LOOKUP, CREATE, mechanisms used when a file is opened or created (LOOKUP, CREATE,
skipping to change at line 12470 skipping to change at line 12307
<t> <t>
Each open is associated with a specific open-owner while each Each open is associated with a specific open-owner while each
byte-range lock is associated with a lock-owner and an byte-range lock is associated with a lock-owner and an
open-owner, the latter being the open-owner associated with the open-owner, the latter being the open-owner associated with the
open file under which the LOCK operation was done. Delegations open file under which the LOCK operation was done. Delegations
and layouts, on the other hand, are not associated with a and layouts, on the other hand, are not associated with a
specific owner but are associated with the client as a whole specific owner but are associated with the client as a whole
(identified by a client ID). (identified by a client ID).
</t> </t>
</section> </section>
<!-- [auth] "State-owner Definition" -->
<section numbered="true" toc="default"> <section numbered="true" toc="default">
<name>Use of the Stateid and Locking</name> <name>Use of the Stateid and Locking</name>
<t> <t>
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 that change the size purposes of this section, SETATTR operations that 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 sizes (i.e., the byte-range truncated or added to the between the old and new sizes (i.e., the byte-range truncated or added to the
file by means of the SETATTR), even where SETATTR is not explicitly file by means of the SETATTR), even where SETATTR is not explicitly
mentioned in the text. The stateid passed to one of these operations must mentioned in the text. The stateid passed to one of these operations must
be one that represents an open, a set of byte-range locks, or a be one that represents an open, a set of byte-range locks, or a
skipping to change at line 12641 skipping to change at line 12477
used, the server knows that the READ, WRITE, or SETATTR used, the server knows that the READ, WRITE, or SETATTR
does not conflict with the delegation but is sent under does not conflict with the delegation but is sent under
the aegis of the delegation. Even though it is possible the aegis of the delegation. Even though it is possible
for the server to determine from the client ID (via for the server to determine from the client ID (via
the session ID) that the client does in fact have a the session ID) that the client does in fact have a
delegation, the server is not obliged to check this, so delegation, the server is not obliged to check this, so
using a special stateid can result in avoidable recall using a special stateid can result in avoidable recall
of the delegation. of the delegation.
</t> </t>
</section> </section>
<!-- [auth] "Use of the Stateid and Locking" -->
</section> </section>
<!-- [auth] "Opens and Byte-Range Locks" -->
<section numbered="true" toc="default"> <section numbered="true" toc="default">
<name>Lock Ranges</name> <name>Lock Ranges</name>
<t> <t>
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, downgrade, or unlock a sub-range of and then either upgrade, downgrade, or unlock a sub-range of
the initial lock, or a byte-range that the initial lock, or a byte-range that
overlaps -- fully or partially -- either with that initial lock or a overlaps -- fully or partially -- either with that initial lock or a
combination of a set of existing locks for the same lock-owner. It combination of a set of existing locks for the same lock-owner. It
is expected that this will be an uncommon type of request. In any 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 case, servers or server file systems may not be able to support
skipping to change at line 12673 skipping to change at line 12507
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 for reasons related to server may not support sub-range requests for reasons related to
the recovery of byte-range locking state in the event of server failure. As the recovery of byte-range locking state in the event of server failure. As
discussed in <xref target="server_failure" format="default"/>, the discussed in <xref target="server_failure" format="default"/>, the
server may employ certain optimizations during recovery that work server may employ certain optimizations during recovery that work
effectively only when the client's behavior during lock recovery is effectively only when the client's behavior during lock recovery is
similar to the client's locking behavior prior to server failure. similar to the client's locking behavior prior to server failure.
</t> </t>
</section> </section>
<!-- [auth] "Lock Ranges" -->
<section numbered="true" toc="default"> <section numbered="true" toc="default">
<name>Upgrading and Downgrading Locks</name> <name>Upgrading and Downgrading Locks</name>
<t> <t>
If a client has a WRITE_LT lock on a byte-range, it can request an atomic If a client has a WRITE_LT lock on a byte-range, it can request an atomic
downgrade of the lock to a READ_LT lock via the LOCK operation, by setting downgrade of the lock to a READ_LT lock via the LOCK operation, by setting
the type to READ_LT. If the server supports atomic downgrade, the the type to READ_LT. If the server supports atomic downgrade, the
request will succeed. If not, it will return NFS4ERR_LOCK_NOTSUPP. The request will succeed. If not, it will return NFS4ERR_LOCK_NOTSUPP. The
client should be prepared to receive this error and, if appropriate, client should be prepared to receive this error and, if appropriate,
report the error to the requesting application. report the error to the requesting application.
</t> </t>
skipping to change at line 12699 skipping to change at line 12532
can be achieved without an existing conflict, the request will can be achieved without an existing conflict, the request will
succeed. Otherwise, the server will return either NFS4ERR_DENIED or succeed. Otherwise, the server will return either NFS4ERR_DENIED or
NFS4ERR_DEADLOCK. The error NFS4ERR_DEADLOCK is returned if the client NFS4ERR_DEADLOCK. The error NFS4ERR_DEADLOCK is returned if the client
sent the LOCK operation with the type set to WRITEW_LT and the server sent the LOCK operation with the type set to WRITEW_LT and the server
has detected a deadlock. The client should be prepared to receive such has detected a deadlock. The client should be prepared to receive such
errors and, if appropriate, report the error to the requesting errors and, if appropriate, report the error to the requesting
application. application.
</t> </t>
</section> </section>
<!-- [auth] "Upgrading and Downgrading Locks" -->
<section anchor="byte_range_seqid" numbered="true" toc="default"> <section anchor="byte_range_seqid" numbered="true" toc="default">
<name>Stateid Seqid Values and Byte-Range Locks</name> <name>Stateid Seqid Values and Byte-Range Locks</name>
<t> <t>
When a LOCK or LOCKU operation is performed, When a LOCK or LOCKU operation is performed,
the stateid returned has the same "other" value as the argument's the stateid returned has the same "other" value as the argument's
stateid, and a stateid, and a
"seqid" value that is incremented (relative to the argument's "seqid" value that is incremented (relative to the argument's
stateid) to reflect the occurrence stateid) to reflect the occurrence
of the LOCK or LOCKU operation. The server <bcp14>MUST</bcp14> increment of the LOCK or LOCKU operation. The server <bcp14>MUST</bcp14> increment
the value of the "seqid" field whenever there is any change the value of the "seqid" field whenever there is any change
skipping to change at line 12722 skipping to change at line 12554
status includes a change from locked to unlocked or the reverse or status includes a change from locked to unlocked or the reverse or
a change from being locked for READ_LT to being locked for WRITE_LT a change from being locked for READ_LT to being locked for WRITE_LT
or the reverse. or the reverse.
</t> </t>
<t> <t>
When there is no such change, as, for example, when a range When there is no such change, as, for example, when a range
already locked for WRITE_LT is locked again for WRITE_LT, the already locked for WRITE_LT is locked again for WRITE_LT, the
server <bcp14>MAY</bcp14> increment the "seqid" value. server <bcp14>MAY</bcp14> increment the "seqid" value.
</t> </t>
</section> </section>
<!-- [auth] "Stateid Sequence Values and Byte-Range Locks" -->
<section anchor="multiple_openowners" numbered="true" toc="default"> <section anchor="multiple_openowners" numbered="true" toc="default">
<name>Issues with Multiple Open-Owners</name> <name>Issues with Multiple Open-Owners</name>
<t> <t>
When the same file is opened by multiple open-owners, When the same file is opened by multiple open-owners,
a client will have multiple OPEN stateids for that a client will have multiple OPEN stateids for that
file, each associated with a different open-owner. file, each associated with a different open-owner.
In that case, there can be multiple LOCK and LOCKU In that case, there can be multiple LOCK and LOCKU
requests for the same lock-owner sent using the requests for the same lock-owner sent using the
different OPEN stateids, and so a situation may different OPEN stateids, and so a situation may
skipping to change at line 12762 skipping to change at line 12593
is a change in the open-owner associated with locks for is a change in the open-owner associated with locks for
the stateid through which a LOCK or LOCKU was done, the the stateid through which a LOCK or LOCKU was done, the
"seqid" field of the stateid <bcp14>MUST</bcp14> be incremented, even "seqid" field of the stateid <bcp14>MUST</bcp14> be incremented, even
if the locking, in terms of lock-owners has not changed. if the locking, in terms of lock-owners has not changed.
When there is a change to the set of locked bytes associated When there is a change to the set of locked bytes associated
with a different stateid for the same lock-owner, i.e., with a different stateid for the same lock-owner, i.e.,
associated with a different open-owner, the "seqid" value associated with a different open-owner, the "seqid" value
for that stateid <bcp14>MUST NOT</bcp14> be incremented. for that stateid <bcp14>MUST NOT</bcp14> be incremented.
</t> </t>
</section> </section>
<!-- [auth] "Issues with Multiple Open-Owners" -->
<section anchor="blocking_locks" numbered="true" toc="default"> <section anchor="blocking_locks" numbered="true" toc="default">
<name>Blocking Locks</name> <name>Blocking Locks</name>
<t> <t>
Some clients require the support of blocking locks. While NFSv4.1 Some clients require the support of blocking locks. While NFSv4.1
provides a callback when a previously unavailable lock becomes provides a callback when a previously unavailable lock becomes
available, this is an <bcp14>OPTIONAL</bcp14> feature and clients cannot available, this is an <bcp14>OPTIONAL</bcp14> feature and clients cannot
depend on its presence. Clients need to be prepared to continually depend on its presence. Clients need to be prepared to continually
poll for the lock. This presents a fairness problem. Two of poll for the lock. This presents a fairness problem. Two of
the lock types, READW_LT and WRITEW_LT, are used to indicate to the the lock types, READW_LT and WRITEW_LT, are used to indicate to the
server that the client is requesting a blocking lock. When the server that the client is requesting a blocking lock. When the
skipping to change at line 12820 skipping to change at line 12650
client should take notice of this, but, since this is a hint, cannot client should take notice of this, but, since this is a hint, cannot
rely on a CB_NOTIFY_LOCK always being done. A client may reasonably rely on a CB_NOTIFY_LOCK always being done. A client may reasonably
reduce the frequency with which it polls for a denied lock, since the reduce the frequency with which it polls for a denied lock, since the
greater latency that might occur is likely to be eliminated given a greater latency that might occur is likely to be eliminated given a
prompt callback, but it still needs to poll. When it receives a prompt callback, but it still needs to poll. When it receives a
CB_NOTIFY_LOCK, it should promptly try to obtain the lock, but it CB_NOTIFY_LOCK, it should promptly try to obtain the lock, but it
should be aware that other clients may be polling and that the server is under should be aware that other clients may be polling and that the server is under
no obligation to reserve the lock for that particular client. no obligation to reserve the lock for that particular client.
</t> </t>
</section> </section>
<!-- [auth] title="Blocking Locks" -->
<section anchor="share_reserve" numbered="true" toc="default"> <section anchor="share_reserve" numbered="true" toc="default">
<name>Share Reservations</name> <name>Share Reservations</name>
<t> <t>
A share reservation is a mechanism to control access to a file. It is A share reservation is a mechanism to control access to a file. It is
a separate and independent mechanism from byte-range locking. When a a separate and independent mechanism from byte-range locking. When a
client opens a file, it sends an OPEN operation to the server client opens a file, it sends an OPEN operation to the server
specifying the type of access required (READ, WRITE, or BOTH) and the specifying the type of access required (READ, WRITE, or BOTH) and the
type of access to deny others (OPEN4_SHARE_DENY_NONE, type of access to deny others (OPEN4_SHARE_DENY_NONE,
OPEN4_SHARE_DENY_READ, OPEN4_SHARE_DENY_WRITE, or OPEN4_SHARE_DENY_BOTH). If OPEN4_SHARE_DENY_READ, OPEN4_SHARE_DENY_WRITE, or OPEN4_SHARE_DENY_BOTH). If
the OPEN fails, the client will fail the application's open request. the OPEN fails, the client will fail the application's open request.
</t> </t>
<t> <t>
Pseudo-code definition of the semantics: Pseudo-code definition of the semantics:
</t> </t>
<sourcecode type=""><![CDATA[ <sourcecode type="pseudocode"><![CDATA[
if (request.access == 0) { if (request.access == 0) {
return (NFS4ERR_INVAL) return (NFS4ERR_INVAL)
} else { } else {
if ((request.access & file_state.deny)) || if ((request.access & file_state.deny)) ||
(request.deny & file_state.access)) { (request.deny & file_state.access)) {
return (NFS4ERR_SHARE_DENIED) return (NFS4ERR_SHARE_DENIED)
} }
return (NFS4ERR_OK);]]></sourcecode> return (NFS4ERR_OK);]]></sourcecode>
<t> <t>
When doing this checking of share reservations on OPEN, the current When doing this checking of share reservations on OPEN, the current
file_state used in the algorithm includes bits that reflect all file_state used in the algorithm includes bits that reflect all
current opens, including those for the open-owner making the current opens, including those for the open-owner making the
new OPEN request. new OPEN request.
</t> </t>
<t> <t>
The constants used for the OPEN and OPEN_DOWNGRADE operations for the The constants used for the OPEN and OPEN_DOWNGRADE operations for the
access and deny fields are as follows: access and deny fields are as follows:
</t> </t>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
const OPEN4_SHARE_ACCESS_READ = 0x00000001; const OPEN4_SHARE_ACCESS_READ = 0x00000001;
const OPEN4_SHARE_ACCESS_WRITE = 0x00000002; const OPEN4_SHARE_ACCESS_WRITE = 0x00000002;
const OPEN4_SHARE_ACCESS_BOTH = 0x00000003; const OPEN4_SHARE_ACCESS_BOTH = 0x00000003;
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;]]></sourcecode> const OPEN4_SHARE_DENY_BOTH = 0x00000003;]]></sourcecode>
</section> </section>
<!-- [auth] "Share Reservations" -->
<section numbered="true" toc="default"> <section numbered="true" toc="default">
<name>OPEN/CLOSE Operations</name> <name>OPEN/CLOSE Operations</name>
<t> <t>
To provide correct share semantics, a client <bcp14>MUST</bcp14> use the OPEN To provide correct share semantics, a client <bcp14>MUST</bcp14> 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 to access and what access, if any, to deny. Even if the client intends to
use a special stateid for anonymous state or READ bypass, use a special stateid for anonymous state or READ bypass,
it must still obtain the it must still obtain the
filehandle for the regular file with the OPEN operation so the filehandle for the regular file with the OPEN operation so the
appropriate share semantics can be applied. Clients that do not appropriate share semantics can be applied. Clients that do not
skipping to change at line 12906 skipping to change at line 12734
assume that the client has the least access. For example, if one assume that 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 second client could only read the file using the special read
bypass stateid. The second client could not WRITE the file bypass stateid. The second client could not WRITE the file
at all because it would at all because it would
not have a valid stateid from OPEN and the special anonymous stateid would not have a valid stateid from OPEN and the special anonymous stateid would
not be allowed access. not be allowed access.
</t> </t>
</section> </section>
<!-- [auth] "OPEN/CLOSE Operations" -->
<section anchor="open_upgrade" numbered="true" toc="default"> <section anchor="open_upgrade" numbered="true" toc="default">
<name>Open Upgrade and Downgrade</name> <name>Open Upgrade and Downgrade</name>
<t> <t>
When an OPEN is done for a file and the open-owner for which the OPEN When an OPEN is done for a file and the open-owner for which the OPEN
is being done already has the file open, the result is to upgrade the is being done already has the file open, the result is to upgrade the
open file status maintained on the server to include the access and open file status maintained on the server to include the access and
deny bits specified by the new OPEN as well as those for the existing deny bits specified by the new OPEN as well as those for the existing
OPEN. The result is that there is one open file, as far as the OPEN. The result is that there is one open file, as far as the
protocol is concerned, and it includes the union of the access and protocol is concerned, and it includes the union of the access and
deny bits for all of the OPEN requests completed. The OPEN deny bits for all of the OPEN requests completed. The OPEN
skipping to change at line 12955 skipping to change at line 12782
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 make subset) than previously. The OPEN_DOWNGRADE operation is used to make
the necessary change and the client should use it to update the server the necessary change and the client should use it to update the server
so that share reservation requests by other clients are handled so that share reservation requests by other clients are handled
properly. The stateid returned has the same "other" field as properly. The stateid returned has the same "other" field as
that passed to the server. The "seqid" value in the returned that passed to the server. The "seqid" value in the returned
stateid <bcp14>MUST</bcp14> be incremented, even in situations in which there is stateid <bcp14>MUST</bcp14> be incremented, even in situations in which there is
no change to the access and deny bits for the file. no change to the access and deny bits for the file.
</t> </t>
</section> </section>
<!-- [auth] "Open Upgrade and Downgrade" -->
<section anchor="parallel_opens" numbered="true" toc="default"> <section anchor="parallel_opens" numbered="true" toc="default">
<name>Parallel OPENs</name> <name>Parallel OPENs</name>
<t> <t>
Unlike the case of NFSv4.0, in which OPEN operations for the same Unlike the case of NFSv4.0, in which OPEN operations for the same
open-owner are inherently serialized because of the owner-based seqid, open-owner are inherently serialized because of the owner-based seqid,
multiple OPENs for the same open-owner may be done in parallel. When multiple OPENs for the same open-owner may be done in parallel. When
clients do this, they may encounter situations in which, because clients do this, they may encounter situations in which, because
of the existence of hard links, two OPEN operations may turn out of the existence of hard links, two OPEN operations may turn out
to open the same file, with a later OPEN performed being an upgrade of to open the same file, with a later OPEN performed being an upgrade of
the first, with this fact only visible to the the first, with this fact only visible to the
skipping to change at line 12986 skipping to change at line 12812
<t> <t>
When the possibility exists that the client will send multiple When the possibility exists that the client will send multiple
OPENs for the same open-owner in parallel, it may be the case that OPENs for the same open-owner in parallel, it may be the case that
an open upgrade may happen without the client knowing beforehand an open upgrade may happen without the client knowing beforehand
that this could happen. Because of this possibility, CLOSEs and that this could happen. Because of this possibility, CLOSEs and
OPEN_DOWNGRADEs should generally be sent with a non-zero seqid OPEN_DOWNGRADEs should generally be sent with a non-zero seqid
in the stateid, to avoid the possibility that the status change in the stateid, to avoid the possibility that the status change
associated with an open upgrade is not inadvertently lost. associated with an open upgrade is not inadvertently lost.
</t> </t>
</section> </section>
<!-- [auth] "Parallel OPENs" -->
<section anchor="open_br_reclaim" numbered="true" toc="default"> <section anchor="open_br_reclaim" numbered="true" toc="default">
<name>Reclaim of Open and Byte-Range Locks</name> <name>Reclaim of Open and Byte-Range Locks</name>
<t> <t>
Special forms of the LOCK and OPEN operations are provided when it Special forms of the LOCK and OPEN operations are provided when it
is necessary to re-establish byte-range locks or opens after a is necessary to re-establish byte-range locks or opens after a
server failure. server failure.
</t> </t>
<ul spacing="normal"> <ul spacing="normal">
<li> <li>
To reclaim existing opens, an OPEN operation is performed To reclaim existing opens, an OPEN operation is performed
skipping to change at line 13014 skipping to change at line 12839
To reclaim byte-range locks, a LOCK operation with the To reclaim byte-range locks, a LOCK operation with the
reclaim parameter set to true is used. reclaim parameter set to true is used.
</li> </li>
</ul> </ul>
<t> <t>
Reclaims of opens associated with delegations are discussed in Reclaims of opens associated with delegations are discussed in
<xref target="delegation_recovery" format="default"/>. <xref target="delegation_recovery" format="default"/>.
</t> </t>
</section> </section>
</section> </section>
<!--[auth] "File Locking and Share Reservations" -->
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- [auth] Copyright (C) The IETF Trust (2007-2008) -->
<!-- [auth] Copyright (C) The Internet Society (2006) -->
<section numbered="true" toc="default"> <section numbered="true" toc="default">
<name>Client-Side Caching</name> <name>Client-Side Caching</name>
<t> <t>
Client-side caching of data, of file attributes, and of file names is Client-side caching of data, of file attributes, and of file names is
essential to providing good performance with the NFS protocol. essential to providing good performance with the NFS protocol.
Providing distributed cache coherence is a difficult problem, and Providing distributed cache coherence is a difficult problem, and
previous versions of the NFS protocol have not attempted it. Instead, previous versions of the NFS protocol have not attempted it. Instead,
several NFS client implementation techniques have been used to reduce several NFS client implementation techniques have been used to reduce
the problems that a lack of coherence poses for users. These the problems that a lack of coherence poses for users. These
techniques have not been clearly defined by earlier protocol techniques have not been clearly defined by earlier protocol
skipping to change at line 13679 skipping to change at line 13500
prescribed handling that the delegated client would apply prescribed handling that the delegated client would apply
(see below). (see below).
</li> </li>
</ul> </ul>
<t> <t>
There are two types of OPEN delegations: OPEN_DELEGATE_READ and OPEN_DELEGATE_WRITE. An OPEN_DELEGATE_READ There are two types of OPEN delegations: OPEN_DELEGATE_READ and OPEN_DELEGATE_WRITE. An OPEN_DELEGATE_READ
delegation allows a client to handle, on its own, requests to open a delegation allows a client to handle, on its own, requests to open a
file for reading that do not deny OPEN4_SHARE_ACCESS_READ access to others. Multiple file for reading that do not deny OPEN4_SHARE_ACCESS_READ access to others. Multiple
OPEN_DELEGATE_READ delegations may be outstanding simultaneously and do not OPEN_DELEGATE_READ delegations may be outstanding simultaneously and do not
conflict. An OPEN_DELEGATE_WRITE delegation allows the client to handle, on its conflict. An OPEN_DELEGATE_WRITE delegation allows the client to handle, on its
own, all opens. Only OPEN_DELEGATE_WRITE delegation may exist for a given own, all opens. Only one OPEN_DELEGATE_WRITE delegation may exist for a given
file at a given time, and it is inconsistent with any OPEN_DELEGATE_READ delegations. file at a given time, and it is inconsistent with any OPEN_DELEGATE_READ delegations.
</t> </t>
<t> <t>
When a client has an OPEN_DELEGATE_READ delegation, it is assured that When a client has an OPEN_DELEGATE_READ delegation, it is assured that
neither the contents, the attributes (with the exception of neither the contents, the attributes (with the exception of
time_access), nor the names of any time_access), nor the names of any
links to the file will change without its knowledge, so long as the links to the file will change without its knowledge, so long as the
delegation is held. When a client has an OPEN_DELEGATE_WRITE delegation, it delegation is held. When a client has an OPEN_DELEGATE_WRITE delegation, it
may modify the file data locally since no other client will be may modify the file data locally since no other client will be
accessing the file's data. The client holding an OPEN_DELEGATE_WRITE delegation accessing the file's data. The client holding an OPEN_DELEGATE_WRITE delegation
skipping to change at line 14085 skipping to change at line 13906
previous CLOSE operation has been sent to the server, a CLOSE previous CLOSE operation has been sent to the server, a CLOSE
operation must be sent to the server. operation must be sent to the server.
</li> </li>
<li> <li>
If a file has other open references at the client, then OPEN If a file has other open references at the client, then OPEN
operations must be sent to the server. The appropriate stateids will operations must be sent to the server. The appropriate stateids will
be provided by the server for subsequent use by the client since the be provided by the server for subsequent use by the client since the
delegation stateid will no longer be valid. These OPEN requests are delegation stateid will no longer be valid. These OPEN requests are
done with the claim type of CLAIM_DELEGATE_CUR. This will allow the done with the claim type of CLAIM_DELEGATE_CUR. This will allow the
presentation of the delegation stateid so that the client can presentation of the delegation stateid so that the client can
establish the appropriate rights to perform the OPEN. (see establish the appropriate rights to perform the OPEN. (See
<xref target="OP_OPEN" format="default"/>, which describes the OPEN operation, <xref target="OP_OPEN" format="default"/>, which describes the OPEN operation,
for details.) for details.)
</li> </li>
<li> <li>
If there are granted byte-range locks, the corresponding LOCK operations If there are granted byte-range locks, the corresponding LOCK operations
need to be performed. This applies to the OPEN_DELEGATE_WRITE delegation case need to be performed. This applies to the OPEN_DELEGATE_WRITE delegation case
only. only.
</li> </li>
<li> <li>
For an OPEN_DELEGATE_WRITE delegation, if For an OPEN_DELEGATE_WRITE delegation, if
skipping to change at line 14902 skipping to change at line 14723
delivery of updates cached at the client. Neither of these delivery of updates cached at the client. Neither of these
goals applies to directories protected by OPEN_DELEGATE_READ delegations and goals applies to directories protected by OPEN_DELEGATE_READ delegations and
notifications. Thus, no provision is made for reclaiming notifications. Thus, no provision is made for reclaiming
directory delegations in the event of client or server restart. directory delegations in the event of client or server restart.
The client can simply establish a directory delegation in the The client can simply establish a directory delegation in the
same fashion as was done initially. same fashion as was done initially.
</t> </t>
</section> </section>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007-2008) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="NEW11" numbered="true" toc="default"> <section anchor="NEW11" numbered="true" toc="default">
<name>Multi-Server Namespace</name> <name>Multi-Server Namespace</name>
<!-- [rfced] Would the following change improve readability
In Section 11?
Current:
Use of multi-server namespaces can provide many advantages,
by separating a file system's logical position in a namespace
from the (possibly changing) logistical and administrative
considerations that result in particular file systems being
located on particular servers via a single network access
paths known in advance or determined using DNS.
Perhaps:
The use of multi-server namespaces can provide many advantages
by separating a file system's logical position in a namespace
from the (possibly changing) logistical and administrative
considerations that cause a particular file system to be
located on a particular server via a single network access
path that has to be known in advance or determined using DNS.
<t> <t>
NFSv4.1 supports attributes that allow a namespace to extend NFSv4.1 supports attributes that allow a namespace to extend
beyond the boundaries of a single server. It is desirable beyond the boundaries of a single server. It is desirable
that clients and servers support construction of such that clients and servers support construction of such
multi-server namespaces. Use of such multi-server namespaces multi-server namespaces. Use of such multi-server namespaces
is <bcp14>OPTIONAL</bcp14>; however, and for many purposes, is <bcp14>OPTIONAL</bcp14>; however, and for many purposes,
single-server namespaces are perfectly acceptable. Use of single-server namespaces are perfectly acceptable. The use
multi-server namespaces can provide many advantages, by of multi-server namespaces can provide many advantages
separating a file system's logical position in a namespace from by separating a file system's logical position in a namespace
the (possibly changing) logistical and administrative from the (possibly changing) logistical and administrative
considerations that result in particular file systems being considerations that cause a particular file system to be
located on particular servers via a single network access path known located on a particular server via a single network access
in advance or determined using DNS. path that has to be known in advance or determined using DNS.
</t> </t>
<section anchor="SEC11-TERM" numbered="true" toc="default"> <section anchor="SEC11-TERM" numbered="true" toc="default">
<name>Terminology</name> <name>Terminology</name>
<t> <t>
In this section as a whole (i.e., within all of <xref target="NEW11" format="default"/>), In this section as a whole (i.e., within all of <xref target="NEW11" format="default"/>),
the phrase "client ID" always refers to the the phrase "client ID" always refers to the
64-bit shorthand identifier assigned by the server (a clientid4) 64-bit shorthand identifier assigned by the server (a clientid4)
and never to the structure that the client uses to identify itself and never to the structure that the client uses to identify itself
to the server (called an nfs_client_id4 or client_owner in NFSv4.0 to the server (called an nfs_client_id4 or client_owner in NFSv4.0
and NFSv4.1, respectively). The opaque identifier within those and NFSv4.1, respectively). The opaque identifier within those
skipping to change at line 15225 skipping to change at line 15024
<li> <li>
Help the client efficiently effect as seamless Help the client efficiently effect as seamless
a transition as possible among multiple file system instances, a transition as possible among multiple file system instances,
when and if that should be necessary. when and if that should be necessary.
</li> </li>
<li> <li>
Guide the selection of the appropriate Guide the selection of the appropriate
connection type to be used when establishing a connection. connection type to be used when establishing a connection.
</li> </li>
</ul> </ul>
<!-- [rfced] Would the following change improve readability in <t>
Section 11.2?
Current:
Within the fs_locations_info attribute, each
fs_locations_server4 entry corresponds to a file system
location entry with the fls_server field designating the
server and with the location pathname within the server's
pseudo-fs given by the fl_rootpath field of the encompassing
fs_locations_item4.
Perhaps:
Within the fs_locations_info attribute, each Within the fs_locations_info attribute, each
fs_locations_server4 entry corresponds to a file system fs_locations_server4 entry corresponds to a file system
location entry: the fls_server field designates the server, location entry: the fls_server field designates the server,
and the fl_rootpath field of the encompassing fs_locations_item4 and the fl_rootpath field of the encompassing fs_locations_item4
gives the location pathname within the server's pseudo-fs. gives the location pathname within the server's pseudo-fs.
<t>
Within the fs_locations_info attribute, each fs_locations_server4
entry corresponds to a file system location entry with the
fls_server field designating the server and with the location pathname
within the server's pseudo-fs given by the fl_rootpath field of the
encompassing fs_locations_item4.
</t> </t>
<t> <t>
The fs_locations attribute defined in NFSv4.0 is also a part of The fs_locations attribute defined in NFSv4.0 is also a part of
NFSv4.1. This attribute only allows specification of the file system NFSv4.1. This attribute only allows specification of the file system
locations where the data corresponding to a given file locations where the data corresponding to a given file
system may be found. Servers <bcp14>SHOULD</bcp14> make this attribute available system may be found. Servers <bcp14>SHOULD</bcp14> make this attribute available
whenever fs_locations_info is supported, but client use of whenever fs_locations_info is supported, but client use of
fs_locations_info is preferable because it provides more information. fs_locations_info is preferable because it provides more information.
</t> </t>
<t> <t>
skipping to change at line 15592 skipping to change at line 15373
server in order to increase the speed of data transfer. server in order to increase the speed of data transfer.
A client may determine the set of network addresses to use to A client may determine the set of network addresses to use to
access a given file system in a number of ways: access a given file system in a number of ways:
</t> </t>
<ul spacing="normal"> <ul spacing="normal">
<li> <li>
When the name of the server is known to the client, it may use When the name of the server is known to the client, it may use
DNS to obtain a set of network addresses to use in DNS to obtain a set of network addresses to use in
accessing the server. accessing the server.
</li> </li>
<!-- [rfced] In Section 11.5.2, should the following be
"so_major_id" rather than "so_major"?
Current:
Once the candidate addresses have been determined and
EXCHANGE_ID done to the proper server, only the value of
the so_major field returned by the servers in question
determines whether a trunking relationship actually exists.
<li> <li>
The client may fetch the file system location attribute for the The client may fetch the file system location attribute for the
file system. This will file system. This will
provide either the name of the server (which can be turned provide either the name of the server (which can be turned
into a set of network addresses using DNS) or into a set of network addresses using DNS) or
a set of server-trunkable location entries. Using the latter a set of server-trunkable location entries. Using the latter
alternative, the server can alternative, the server can
provide addresses it regards as desirable to use provide addresses it regards as desirable to use
to access the file system in question. Although these entries can to access the file system in question. Although these entries can
contain port numbers, these port numbers are not used in determining contain port numbers, these port numbers are not used in determining
trunking relationships. Once the candidate addresses have been trunking relationships. Once the candidate addresses have been
determined and EXCHANGE_ID done to the proper server, only the value determined and EXCHANGE_ID done to the proper server, only the value
of the so_major field returned by the servers in question determines of the so_major_id field returned by the servers in question determines
whether a trunking relationship actually exists. whether a trunking relationship actually exists.
</li> </li>
</ul> </ul>
<!-- [rfced] In Section 11.5.2, we've made the following change
to improve readability. Please let us know if any changes are
necessary.
Original:
It should be noted that the client, when it fetches a location
attribute for a file system, may encounter multiple entries for
a number of reasons, so that, when determining trunking
information, it may have to bypass addresses not trunkable with
one already known.
Current:
When the client fetches a location attribute for a file system,
it should be noted that the client may encounter multiple entries
for a number of reasons, such that when it determines trunking
information, it may have to bypass addresses not trunkable with
one already known.
<t> <t>
When the client fetches a location attribute When the client fetches a location attribute
for a file system, it should be noted that the client may encounter multiple entries for a number of for a file system, it should be noted that the client may encounter multiple entries for a number of
reasons, such that when it determines trunking information, it may have reasons, such that when it determines trunking information, it may
need
to bypass addresses not trunkable with one already known. to bypass addresses not trunkable with one already known.
</t> </t>
<t> <t>
The server can provide location entries that include either The server can provide location entries that include either
names or network addresses. It might use the latter form names or network addresses. It might use the latter form
because of DNS-related security concerns or because the set because of DNS-related security concerns or because the set
of addresses of addresses
to be used might require active management by the server. to be used might require active management by the server.
</t> </t>
<t> <t>
skipping to change at line 15685 skipping to change at line 15440
possibility of changing it within the scope of a single connection. possibility of changing it within the scope of a single connection.
</t> </t>
<t> <t>
The two file system location attributes differ as to the The two file system location attributes differ as to the
information made available in this regard. The fs_locations attribute provides no information information made available in this regard. The fs_locations attribute provides no information
to support connection type selection. As a result, clients to support connection type selection. As a result, clients
supporting multiple connection types would need to attempt to supporting multiple connection types would need to attempt to
establish connections using multiple connection types until establish connections using multiple connection types until
the one preferred by the client is successfully established. the one preferred by the client is successfully established.
</t> </t>
<!-- [rfced] Does the following improve readability in <t>
Section 11.5.3?
Current:
The fs_locations_info attribute includes a flag, FSLI4TF_RDMA,
which, when set indicates that RPC-over-RDMA support is available
using the specified location entry, by "stepping up" an existing
TCP connection to include support for RDMA operation. This flag
makes it convenient for a client wishing to use RDMA. When this
flag is set, it can establish a TCP connection and then convert
that connection to use RDMA by using the step-up facility.
Perhaps:
The fs_locations_info attribute includes the FSLI4TF_RDMA flag, The fs_locations_info attribute includes the FSLI4TF_RDMA flag,
which is convenient for a client wishing to use RDMA. When this which is convenient for a client wishing to use RDMA. When this
flag is set, it indicates that RPC-over-RDMA support is available flag is set, it indicates that RPC-over-RDMA support is available
using the specified location entry. A client can establish a TCP using the specified location entry. A client can establish a TCP
connection and then convert that connection to use RDMA by using connection and then convert that connection to use RDMA by using
the step-up facility. the step-up facility.
<t> </t>
The fs_locations_info attribute includes a flag, FSLI4TF_RDMA,
which, when set indicates that RPC-over-RDMA support is available
using the specified location entry, by "stepping up" an existing
TCP connection to include support for RDMA operation. This flag
makes it convenient for a client wishing to use RDMA. When this
flag is set, it can establish a TCP connection and then convert
that connection to use RDMA by using the step-up facility.
</t>
<t> <t>
Irrespective of the particular attribute used, when there is Irrespective of the particular attribute used, when there is
no indication that a step-up operation can be performed, no indication that a step-up operation can be performed,
a client supporting RDMA operation can establish a new RDMA a client supporting RDMA operation can establish a new RDMA
connection, and it can be bound to connection, and it can be bound to
the session already established by the the session already established by the
TCP connection, allowing the TCP connection to be dropped TCP connection, allowing the TCP connection to be dropped
and the session converted to further use in RDMA mode, if and the session converted to further use in RDMA mode, if
the server supports that. the server supports that.
</t> </t>
skipping to change at line 15756 skipping to change at line 15490
(typically read-only) file system data supplemented by (typically read-only) file system data supplemented by
possible asynchronous propagation of updates. Alternatively, possible asynchronous propagation of updates. Alternatively,
they may provide for the use of various forms of server they may provide for the use of various forms of server
clustering in which multiple servers provide alternate clustering in which multiple servers provide alternate
ways of accessing the same physical file system. How the ways of accessing the same physical file system. How the
difference between replicas affects file system transitions difference between replicas affects file system transitions
can be represented within the fs_locations and fs_locations_info can be represented within the fs_locations and fs_locations_info
attributes, and how the client deals with file system transition attributes, and how the client deals with file system transition
issues will be discussed in detail in later sections. issues will be discussed in detail in later sections.
</t> </t>
<!-- [rfced] Does the following improve readability in
Section 11.5.4?
Current:
Because of this lack of specificity, many applications may find
the use of migration more appropriate, since, in that case, the
server, when effecting the transition, has established a point
in time such that all updates made before that can propagated to
the new replica as part of the migration event.
Perhaps:
Due to this lack of specificity, many applications may find the
use of migration more appropriate because a server can propagate
all updates made before an established point in time to the new
replica as part of the migration event.
<t> <t>
Although the location attributes provide some information about Although the location attributes provide some information about
the nature of the inter-replica transition, many aspects of the the nature of the inter-replica transition, many aspects of the
semantics of possible asynchronous updates are not currently described semantics of possible asynchronous updates are not currently described
by the protocol, which makes it necessary for clients using replication by the protocol, which makes it necessary for clients using replication
to switch among replicas undergoing change to familiarize themselves to switch among replicas undergoing change to familiarize themselves
with the semantics of the update approach used. Because of this with the semantics of the update approach used.
lack of specificity, many applications may find the use of migration more Due to this lack of specificity, many applications may find the
appropriate, since, in that case, the server, when effecting the use of migration more appropriate because a server can propagate
transition, has established a point in time such that all updates made all updates made before an established point in time to the new
before that can propagated to the new replica as part of the migration replica as part of the migration event.
event.
</t> </t>
<section anchor="SEC11-USES-repl-trunk" numbered="true" toc="default"> <section anchor="SEC11-USES-repl-trunk" numbered="true" toc="default">
<name>File System Trunking Presented as Replication</name> <name>File System Trunking Presented as Replication</name>
<t> <t>
In some situations, a file system location entry may indicate In some situations, a file system location entry may indicate
a file system access path to be used as an alternate location, a file system access path to be used as an alternate location,
where trunking, rather than replication, is to be used. The where trunking, rather than replication, is to be used. The
situations in which this is appropriate are limited to those situations in which this is appropriate are limited to those
in which both of the following are true: in which both of the following are true:
</t> </t>
skipping to change at line 15821 skipping to change at line 15538
generally trunked, although trunking may be disallowed when the generally trunked, although trunking may be disallowed when the
attribute fs_locations_info is used: attribute fs_locations_info is used:
</t> </t>
<ul spacing="normal"> <ul spacing="normal">
<li> <li>
<t> <t>
When the fs_locations_info attribute shows the two entries When the fs_locations_info attribute shows the two entries
as not having the same simultaneous-use class, trunking is as not having the same simultaneous-use class, trunking is
inhibited, and the two access paths cannot be used together. inhibited, and the two access paths cannot be used together.
</t> </t>
<!-- [rfced] We've made the following change to improve
readability in Section 11.5.4.1. Please let us know if any other
changes are necessary.
Original:
In this case, the two paths can be used serially with no
transition activity required on the part of the client. In this
case, any transition between access paths is transparent, and the
client, in transferring access from one to the other, is acting
as it would in the event that communication is interrupted, with
a new connection and possibly a new session being established to
continue access to the same file system.
Current:
In this case, the two paths can be used serially with no
transition activity required on the part of the client, and any
transition between access paths is transparent. In transferring
access from one to the other, the client acts as if communication
were interrupted, establishing a new connection and possibly a
new session to continue access to the same file system.
<t> <t>
In this case, the two paths can be used serially with no In this case, the two paths can be used serially with no
transition activity required on the part of the client, and any transition activity required on the part of the client, and any
transition between access paths is transparent. In transferring transition between access paths is transparent. In transferring
access from one to the other, the client acts as if communication access from one to the other, the client acts as if communication
were interrupted, establishing a new connection and possibly a were interrupted, establishing a new connection and possibly a
new session to continue access to the same file system. new session to continue access to the same file system.
</t> </t>
</li> </li>
<li> <li>
skipping to change at line 16050 skipping to change at line 15746
adapt to client physical location or to effect load balancing. adapt to client physical location or to effect load balancing.
When both read-only and read-write file systems are present, When both read-only and read-write file systems are present,
some of the read-only locations might not be absolutely up-to-date some of the read-only locations might not be absolutely up-to-date
(as they would have to be in the case of replication and (as they would have to be in the case of replication and
migration). Servers may also specify file system locations migration). Servers may also specify file system locations
that include client-substituted variables so that different that include client-substituted variables so that different
clients are referred to different file systems (with different clients are referred to different file systems (with different
data contents) based on client attributes such as CPU data contents) based on client attributes such as CPU
architecture. architecture.
</t> </t>
<!-- [rfced] We have made the following change to improve
readability in Section 11.5.6. Please let us know if any other
changes are required.
Original:
When the fs_locations_info attribute is such that that there
are multiple possible targets listed, the relationships among
them may be important to the client in selecting which one
to use.
Current:
If the fs_locations_info attribute lists multiple possible
targets, the relationships among them may be important to the
client in selecting which one to use.
<t> <t>
If the fs_locations_info attribute lists multiple possible targets, If the fs_locations_info attribute lists multiple possible targets,
the relationships among them may be important to the client in the relationships among them may be important to the client in
selecting which one to use. selecting which one to use.
The same rules specified in <xref target="SEC11-USES-migr" format="default"/> The same rules specified in <xref target="SEC11-USES-migr" format="default"/>
below regarding multiple migration targets below regarding multiple migration targets
apply to these multiple replicas as well. For example, the apply to these multiple replicas as well. For example, the
client might prefer a writable target on a server that has client might prefer a writable target on a server that has
additional writable additional writable
replicas to which it subsequently might switch. Note that, replicas to which it subsequently might switch. Note that,
skipping to change at line 16342 skipping to change at line 16023
</li> </li>
<li> <li>
Those in which access to the current file system instance is retained, while Those in which access to the current file system instance is retained, while
the network path used to access that instance is changed. This case is the network path used to access that instance is changed. This case is
discussed in <xref target="SEC11-nwa" format="default"/>. discussed in <xref target="SEC11-nwa" format="default"/>.
</li> </li>
</ul> </ul>
</section> </section>
<section anchor="SEC11-nwa" numbered="true" toc="default"> <section anchor="SEC11-nwa" numbered="true" toc="default">
<name>Effecting Network Endpoint Transitions</name> <name>Effecting Network Endpoint Transitions</name>
<!-- [rfced] In Section 11.10, the following sentence appears
to be missing the last item in its list:
Current:
In each of these cases, the same fsid, filehandles, stateids,
client IDs, and are used to continue access, with a continuity
of lock state.
<t> <t>
The endpoints used to access a particular file system instance The endpoints used to access a particular file system instance
may change in a number of ways, as listed below. In each of these may change in a number of ways, as listed below. In each of these
cases, the same fsid, filehandles, stateids, client IDs, and are cases, the same fsid, client IDs, filehandles, and stateids are
used to continue access, with a continuity of lock state. In used to continue access, with a continuity of lock state. In
many cases, the same sessions can also be used. many cases, the same sessions can also be used.
</t> </t>
<t> <t>
The appropriate action depends on the set of replacement addresses The appropriate action depends on the set of replacement addresses
that are available for use that are available for use
(i.e., server endpoints that are server-trunkable with one previously (i.e., server endpoints that are server-trunkable with one previously
being used). being used).
</t> </t>
<ul spacing="normal"> <ul spacing="normal">
skipping to change at line 16375 skipping to change at line 16048
When use of a particular address is to cease, and there is When use of a particular address is to cease, and there is
also another address also another address
currently in use that is server-trunkable with it, requests currently in use that is server-trunkable with it, requests
that would have been issued on the address whose use is to be that would have been issued on the address whose use is to be
discontinued can be issued on the remaining address(es). When an discontinued can be issued on the remaining address(es). When an
address is server-trunkable but not session-trunkable with the address is server-trunkable but not session-trunkable with the
address whose use is to be discontinued, the request might need address whose use is to be discontinued, the request might need
to be modified to reflect the fact that a different session will to be modified to reflect the fact that a different session will
be used. be used.
</li> </li>
<!-- [rfced] We're having difficulty parsing the following sentence
in Section 11.10:
Current:
Since any two non-port-specific server endpoints that share a
network address are inherently session-trunkable, the client
can use BIND_CONN_TO_SESSION to access the existing session
using the new connection and proceed to access the file system
using the new connection.
Perhaps:
Since any two non-port-specific server endpoints that share a
network address are inherently session-trunkable, the client
can use BIND_CONN_TO_SESSION to access the existing session
with the new connection.
<li> <li>
When use of a particular connection is to cease, as indicated When use of a particular connection is to cease, as indicated
by receiving NFS4ERR_MOVED when using that connection, but by receiving NFS4ERR_MOVED when using that connection, but
that address is that address is
still indicated as accessible according to the appropriate still indicated as accessible according to the appropriate
file system location file system location
entries, it is likely that requests can be issued on a new entries, it is likely that requests can be issued on a new
connection of a different connection type once that connection connection of a different connection type once that connection
is established. Since any two non-port-specific is established.
server endpoints that share a network address are inherently Since any two non-port-specific server endpoints that share a
session-trunkable, the client can use BIND_CONN_TO_SESSION network address are inherently session-trunkable, the client
to access the existing session using the new connection and can use BIND_CONN_TO_SESSION to access the existing session
proceed to access the file system using the new connection. with the new connection.
</li> </li>
<li> <li>
When there are no potential replacement addresses in use, but there When there are no potential replacement addresses in use, but there
are valid addresses session-trunkable with the one whose use is are valid addresses session-trunkable with the one whose use is
to be discontinued, the client can use BIND_CONN_TO_SESSION to be discontinued, the client can use BIND_CONN_TO_SESSION
to access the existing session using the new address. Although to access the existing session using the new address. Although
the target session will generally be accessible, there may be the target session will generally be accessible, there may be
rare situations in which that session is no longer accessible rare situations in which that session is no longer accessible
when an attempt is made to bind the new connection to it. In this when an attempt is made to bind the new connection to it. In this
case, the client can create a new session to enable continued case, the client can create a new session to enable continued
skipping to change at line 17225 skipping to change at line 16882
</t> </t>
<t> <t>
This condition continues on subsequent attempts to access This condition continues on subsequent attempts to access
the file system in question. The only way the client the file system in question. The only way the client
can avoid the error is to cease accessing the file system in can avoid the error is to cease accessing the file system in
question at its old server location and access it instead question at its old server location and access it instead
using a different address at which it is now available. using a different address at which it is now available.
</t> </t>
</li> </li>
<li> <li>
<!-- [rfced] We're having difficulty parsing the following <t>
sentence in Section 11.13.1: Whenever a client sends a SEQUENCE operation to a server that
generated state held on that client and associated with a
Current: file system no longer accessible on that server, the response will contain
Whenever a SEQUENCE operation is sent by a client to a server the status bit SEQ4_STATUS_LEASE_MOVED, indicating that there has
which generated state held on that client which is associated been a lease migration.
with a file system that is no longer accessible on the server
at which it was previously available, the response will contain
a lease-migrated indication, with the SEQ4_STATUS_LEASE_MOVED
status bit being set.
Perhaps:
Whenever a client sends a SEQUENCE operation to a server that
generated state held on that client and associated with a
no-longer-accessible file system, the response will contain a
lease-migrated indication with the SEQ4_STATUS_LEASE_MOVED
status bit being set.
<t>
Whenever a SEQUENCE operation is sent by a client to
a server which generated state held on that client which
is associated with a file system that is no longer accessible
on the server at which it was previously available, the response
will contain a lease-migrated indication, with the
SEQ4_STATUS_LEASE_MOVED status bit being set.
</t> </t>
<t> <t>
This condition continues until the client acknowledges This condition continues until the client acknowledges
the notification by fetching a file system location attribute for the the notification by fetching a file system location attribute for the
file system whose network access path is being changed. file system whose network access path is being changed.
When there are multiple such file systems, a location attribute When there are multiple such file systems, a location attribute
for each such file system needs to be fetched. The location for each such file system needs to be fetched. The location
attribute for all migrated file systems needs to be fetched attribute for all migrated file systems needs to be fetched
in order to clear the condition. Even after the condition is cleared, the in order to clear the condition. Even after the condition is cleared, the
client needs to respond by using the location information client needs to respond by using the location information
skipping to change at line 17413 skipping to change at line 17051
migration indications, as long as one can be certain that the migration migration indications, as long as one can be certain that the migration
discovery process would deal with those indications. See below for details. discovery process would deal with those indications. See below for details.
</li> </li>
<li> <li>
For such indications received in all other contexts, the For such indications received in all other contexts, the
appropriate response is to initiate or otherwise provide for the appropriate response is to initiate or otherwise provide for the
execution of migration discovery for file systems execution of migration discovery for file systems
associated with the server IP address returning the indication. associated with the server IP address returning the indication.
</li> </li>
</ul> </ul>
<!-- [rfced] In Section 11.13.2, should "LEASE_MOVED" be instead
"SEQ4_STATUS_LEASE_MOVED"?
For example:
One should not ignore a LEASE_MOVED indication if
the migration discovery process is not able to respond to
the discovery of additional migrating file
systems without additional aid.
<t> <t>
This leaves a potential difficulty in situations in which the This leaves a potential difficulty in situations in which the
migration discovery process is near to completion but is still migration discovery process is near to completion but is still
operating. One should not ignore a LEASE_MOVED indication if operating. One should not ignore a SEQ4_STATUS_LEASE_MOVED indication if
the migration discovery process is not able to respond to the migration discovery process is not able to respond to
the discovery of additional migrating file the discovery of additional migrating file
systems without additional aid. A further complexity relevant in systems without additional aid. A further complexity relevant in
addressing such situations is that a lease-migrated indication may addressing such situations is that a lease-migrated indication may
reflect the server's state at the time the SEQUENCE operation reflect the server's state at the time the SEQUENCE operation
was processed, which may be different from that in effect at the was processed, which may be different from that in effect at the
time the response is received. Because new migration events time the response is received. Because new migration events
may occur at any time, and because a LEASE_MOVED indication may reflect may occur at any time, and because a SEQ4_STATUS_LEASE_MOVED indication may reflect
the situation in effect a considerable time before the indication the situation in effect a considerable time before the indication
is received, special care needs to be taken to ensure that LEASE_MOVED is received, special care needs to be taken to ensure that SEQ4_STATUS_LEASE_MOVED
indications are not inappropriately ignored. indications are not inappropriately ignored.
</t> </t>
<t> <t>
A useful approach to this issue involves the use of separate A useful approach to this issue involves the use of separate
externally-visible migration discovery states for each server. externally-visible migration discovery states for each server.
Separate values could represent the various possible states for Separate values could represent the various possible states for
the migration discovery process for a server: the migration discovery process for a server:
</t> </t>
<ul spacing="normal"> <ul spacing="normal">
<li> <li>
skipping to change at line 17483 skipping to change at line 17112
fss_type != STATUS4_REFERRAL), then a migrated file system has fss_type != STATUS4_REFERRAL), then a migrated file system has
been found. In this situation, it is likely been found. In this situation, it is likely
that the fetch of the file system location attribute has that the fetch of the file system location attribute has
cleared one of the file systems contributing to the cleared one of the file systems contributing to the
lease-migrated indication. lease-migrated indication.
</li> </li>
<li> <li>
In cases in which that happened, the thread cannot know whether In cases in which that happened, the thread cannot know whether
the lease-migrated indication has been cleared, and so it enters the the lease-migrated indication has been cleared, and so it enters the
completion/verification state and proceeds to issue a COMPOUND completion/verification state and proceeds to issue a COMPOUND
to see if the LEASE_MOVED indication has been cleared. to see if the SEQ4_STATUS_LEASE_MOVED indication has been cleared.
</li> </li>
<li> <li>
When the discovery process is in the completion/verification state, When the discovery process is in the completion/verification state,
if other requests get a lease-migrated indication, if other requests get a lease-migrated indication,
they note that it was received. Later, the existence of such they note that it was received. Later, the existence of such
indications is used when the request completes, as described below. indications is used when the request completes, as described below.
</li> </li>
</ul> </ul>
<t> <t>
When the request used in the completion/verification state completes: When the request used in the completion/verification state completes:
skipping to change at line 17519 skipping to change at line 17148
If there have been no lease-migrated indications, the work of If there have been no lease-migrated indications, the work of
migration discovery is considered completed, and it enters the migration discovery is considered completed, and it enters the
non-operating state. Once it enters this state, subsequent non-operating state. Once it enters this state, subsequent
lease-migrated indications will trigger a new migration discovery lease-migrated indications will trigger a new migration discovery
process. process.
</li> </li>
</ul> </ul>
<t> <t>
It should be noted that the process described above is not It should be noted that the process described above is not
guaranteed to terminate, as a long series of new migration guaranteed to terminate, as a long series of new migration
events might continually delay the clearing of the LEASE_MOVED events might continually delay the clearing of the SEQ4_STATUS_LEASE_MOVED
indication. To prevent unnecessary lease expiration, it is indication. To prevent unnecessary lease expiration, it is
appropriate for clients appropriate for clients
to use the discovery of migrations to effect lease to use the discovery of migrations to effect lease
renewal immediately, rather than waiting for the clearing of the renewal immediately, rather than waiting for the clearing of the
LEASE_MOVED indication when the complete set of migrations is SEQ4_STATUS_LEASE_MOVED indication when the complete set of migrations is
available. available.
</t> </t>
<t> <t>
Lease discovery needs to be provided as described above. This Lease discovery needs to be provided as described above. This
ensures that the client discovers file system migrations soon ensures that the client discovers file system migrations soon
enough to renew its leases on each destination server before they enough to renew its leases on each destination server before they
expire. Non-renewal of leases can lead to loss of locking state. expire. Non-renewal of leases can lead to loss of locking state.
While the consequences of such While the consequences of such
loss can be ameliorated through implementations of courtesy locks, loss can be ameliorated through implementations of courtesy locks,
servers are under no obligation to do so, and a conflicting lock request servers are under no obligation to do so, and a conflicting lock request
skipping to change at line 17578 skipping to change at line 17207
<t> <t>
During the first phase of this process, the client proceeds to During the first phase of this process, the client proceeds to
examine file system location entries to find the initial examine file system location entries to find the initial
network address network address
it will use to continue access it will use to continue access
to the file system or its replacement. to the file system or its replacement.
For each location entry that the client examines, the process For each location entry that the client examines, the process
consists of five steps: consists of five steps:
</t> </t>
<ol spacing="normal" type="1"> <ol spacing="normal" type="1">
<!-- [rfced] In the following sentence in Section 11.13.3,
should "server_owner" be "server_owner4"?
Current:
This operation is used to register the client owner (in
the form of a client_owner4) with the server, to obtain
a client ID to be used subsequently to communicate with it,
to obtain that client ID's confirmation status, and to
determine server_owner and scope for the purpose of
determining if the entry is trunkable with the address
previously being used to access the file system...
<li> <li>
Performing an EXCHANGE_ID Performing an EXCHANGE_ID
directed at the location address. This operation is used to directed at the location address. This operation is used to
register the client owner (in the form of a client_owner4) register the client owner (in the form of a client_owner4)
with the server, to obtain a client ID with the server, to obtain a client ID
to be used subsequently to communicate with it, to obtain that to be used subsequently to communicate with it, to obtain that
client ID's confirmation status, and to determine server_owner client ID's confirmation status, and to determine server_owner4
and scope for the purpose of determining if the entry and scope for the purpose of determining if the entry
is trunkable with the address is trunkable with the address
previously being used to access the file system (i.e., that previously being used to access the file system (i.e., that
it represents another network access path to the same it represents another network access path to the same
file system and can share locking state with it). file system and can share locking state with it).
</li> </li>
<li> <li>
Making an initial determination of whether migration has Making an initial determination of whether migration has
occurred. The initial determination will be based occurred. The initial determination will be based
on whether the EXCHANGE_ID results indicate that the on whether the EXCHANGE_ID results indicate that the
skipping to change at line 17625 skipping to change at line 17242
</li> </li>
<li> <li>
Obtaining access to existing session state or creating new Obtaining access to existing session state or creating new
sessions. How this is done depends on the initial sessions. How this is done depends on the initial
determination of whether migration has occurred and determination of whether migration has occurred and
can be done as described in <xref target="V41c-ssmig" format="default"/> below can be done as described in <xref target="V41c-ssmig" format="default"/> below
in the case of migration or as described in in the case of migration or as described in
<xref target="V41c-ssnwas" format="default"/> below <xref target="V41c-ssnwas" format="default"/> below
in the case of a network address transfer without migration. in the case of a network address transfer without migration.
</li> </li>
<!-- [rfced] We are having difficulty parsing the following <li>
sentence in Section 11.13.3: Verifying the trunking relationship assumed in step
2 as discussed in <xref target="PREP-trunk-verify" format="default"/>.
Current:
Although this step will generally confirm the initial
determination, it is possible for verification to fail with the
result that an initial determination that a network address shift
(without migration) has occurred may be invalidated and migration
determined to have occurred.
Perhaps:
Although this step will generally confirm the initial Although this step will generally confirm the initial
determination, it is possible for verification to invalidate determination, it is possible for verification to invalidate
the initial determination of network address shift (without the initial determination of network address shift (without
migration) and instead determine that migration had occurred. migration) and instead determine that migration had occurred.
<li> There is no need to redo
Verifying the trunking relationship assumed in step
2 as discussed in <xref target="PREP-trunk-verify" format="default"/>.
Although this step will generally confirm the initial
determination, it is possible for verification to fail with
the result that an initial determination that a network address
shift (without migration) has occurred may be invalidated and
migration determined to have occurred. There is no need to redo
step 3 above, since it will be possible to continue use of the step 3 above, since it will be possible to continue use of the
session established already. session established already.
</li> </li>
<li> <li>
Obtaining access to existing locking state and/or Obtaining access to existing locking state and/or
re-obtaining it. How this is done depends on the final re-obtaining it. How this is done depends on the final
determination of whether migration has occurred and determination of whether migration has occurred and
can be done as described below in <xref target="V41c-ssmig" format="default"/> can be done as described below in <xref target="V41c-ssmig" format="default"/>
in the case of migration or as described in in the case of migration or as described in
<xref target="V41c-ssnwas" format="default"/> <xref target="V41c-ssnwas" format="default"/>
skipping to change at line 17735 skipping to change at line 17336
new server. new server.
In any of the cases in which Transparent State Migration In any of the cases in which Transparent State Migration
has occurred, it is possible that a session was transferred has occurred, it is possible that a session was transferred
as well. To deal with that possibility, clients can, after as well. To deal with that possibility, clients can, after
doing the EXCHANGE_ID, issue a BIND_CONN_TO_SESSION to doing the EXCHANGE_ID, issue a BIND_CONN_TO_SESSION to
connect the transferred session to a connection to the new connect the transferred session to a connection to the new
server. If that fails, it is an indication that the session server. If that fails, it is an indication that the session
was not transferred and that a new session needs to be created to was not transferred and that a new session needs to be created to
take its place. take its place.
</t> </t>
<!-- [rfced] In the following sentences in Section 11.13.4,
should "sessionid" be instead "session ID"?
Current:
If state merger has taken place, then the associated client ID
may have already had a set of existing sessions, with it
being possible that the sessionid of a given session is the
same as one that might have been migrated. In that event,
a BIND_CONN_TO_SESSION might succeed, even though there
could have been no migration of the session with that sessionid.
<t> <t>
In some situations, it is possible for a BIND_CONN_TO_SESSION In some situations, it is possible for a BIND_CONN_TO_SESSION
to succeed without session migration having occurred. If to succeed without session migration having occurred. If
state merger has taken place, then the associated client ID state merger has taken place, then the associated client ID
may have already had a set of existing sessions, with it may have already had a set of existing sessions, with it
being possible that the sessionid of a given session is the being possible that the session ID of a given session is the
same as one that might have been migrated. In that event, same as one that might have been migrated. In that event,
a BIND_CONN_TO_SESSION might succeed, even though there a BIND_CONN_TO_SESSION might succeed, even though there
could have been no migration of the session with that sessionid. could have been no migration of the session with that session ID.
In such cases, the client will receive sequence errors when the In such cases, the client will receive sequence errors when the
slot sequence values used are not appropriate on the new slot sequence values used are not appropriate on the new
session. When this occurs, the client can create a new a session. When this occurs, the client can create a new a
session and cease using the existing one. session and cease using the existing one.
</t> </t>
<t> <t>
Once the client has determined the initial migration status, Once the client has determined the initial migration status,
and determined that there was a shift to a new server, it and determined that there was a shift to a new server, it
needs to re-establish its locking state, if possible. To enable needs to re-establish its locking state, if possible. To enable
this to happen without loss of the guarantees normally provided by this to happen without loss of the guarantees normally provided by
skipping to change at line 17969 skipping to change at line 17559
or layout. or layout.
</li> </li>
<li> <li>
For locks such as opens and byte-range locks, there will be For locks such as opens and byte-range locks, there will be
information about the owner(s) of the lock. information about the owner(s) of the lock.
</li> </li>
<li> <li>
For recallable/revocable lock types, the current recall status For recallable/revocable lock types, the current recall status
needs to be included. needs to be included.
</li> </li>
<!-- [rfced] We're having difficulty parsing the following
sentence in Section 11.14.2:
Current:
For each lock type, there will be type-specific information, such
as share and deny modes for opens and type and byte ranges for
byte-range locks and layouts.
Perhaps:
For each lock type, there will be type-specific information, such
as share and deny modes for opens, and type and byte ranges for
byte-range locks and layouts.
<li> <li>
For each lock type, there will be type-specific information, such For each lock type, there will be associated type-specific
as share and deny modes for opens and type and byte ranges for information. For opens, this will include share and deny mode
byte-range locks and layouts. while for byte-range locks and layouts, there will be a type and
</li> a byte-range.
</li>
</ul> </ul>
<t> <t>
Such information will most probably be organized by client id string Such information will most probably be organized by client id string
on the destination server on the destination server
so that it can be used to provide appropriate context to each client so that it can be used to provide appropriate context to each client
when it makes itself known to the client. Issues connected with a when it makes itself known to the client. Issues connected with a
client impersonating another by presenting another client's client client impersonating another by presenting another client's client
id string can be addressed using NFSv4.1 state protection features, id string can be addressed using NFSv4.1 state protection features,
as described in <xref target="SECCON" format="default"/>. as described in <xref target="SECCON" format="default"/>.
skipping to change at line 18222 skipping to change at line 17800
Avoid enforcing any sequencing semantics for a particular slot Avoid enforcing any sequencing semantics for a particular slot
until the client has established the starting sequence for that until the client has established the starting sequence for that
slot on the destination server. slot on the destination server.
</li> </li>
<li> <li>
For each slot, avoid For each slot, avoid
returning a cached reply returning NFS4ERR_DELAY or NFS4ERR_MOVED returning a cached reply returning NFS4ERR_DELAY or NFS4ERR_MOVED
until the client has established the starting sequence for that until the client has established the starting sequence for that
slot on the destination server. slot on the destination server.
</li> </li>
<!-- [rfced] We are having difficulty parsing the following in <li>
Section 11.14.3:
Current:
Until the client has established the starting sequence for a
particular slot on the destination server, avoid reporting
NFS4ERR_SEQ_MISORDERED or returning a cached reply returning
NFS4ERR_DELAY or NFS4ERR_MOVED, where the reply consists solely
of a series of operations where the response is NFS4_OK until
the final error.
Perhaps:
Until the client has established the starting sequence for a Until the client has established the starting sequence for a
particular slot on the destination server, avoid reporting particular slot on the destination server, avoid reporting
NFS4ERR_SEQ_MISORDERED or returning a cached reply that contains NFS4ERR_SEQ_MISORDERED or returning a cached reply that contains
either NFS4ERR_DELAY or NFS4ERR_MOVED and consists solely of either NFS4ERR_DELAY or NFS4ERR_MOVED and consists solely of
a series of operations where the response is NFS4_OK until the a series of operations where the response is NFS4_OK until the
final error. final error.
<li>
Until the client has established the starting sequence for a
particular slot on the destination server, avoid reporting NFS4ERR_SEQ_MISORDERED or
returning a cached reply returning NFS4ERR_DELAY or NFS4ERR_MOVED,
where the reply consists solely of a series of operations
where the response is NFS4_OK until the final error.
</li> </li>
</ul> </ul>
<t> <t>
Because of the considerations mentioned above, including the rules Because of the considerations mentioned above, including the rules
for the handling of NFS4ERR_DELAY included in for the handling of NFS4ERR_DELAY included in
<xref target="err_DELAY" format="default"/>, the destination <xref target="err_DELAY" format="default"/>, the destination
server can respond appropriately to SEQUENCE operations received server can respond appropriately to SEQUENCE operations received
from the client by adopting the three policies listed below: from the client by adopting the three policies listed below:
</t> </t>
<ul spacing="normal"> <ul spacing="normal">
skipping to change at line 18713 skipping to change at line 18273
time_modify because these attributes are not available within an time_modify because these attributes are not available within an
absent file system. absent file system.
</t> </t>
</section> </section>
</section> </section>
<section anchor="fs_locations" numbered="true" toc="default"> <section anchor="fs_locations" numbered="true" toc="default">
<name>The Attribute fs_locations</name> <name>The Attribute fs_locations</name>
<t> <t>
The fs_locations attribute is structured in the following way: The fs_locations attribute is structured in the following way:
</t> </t>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct fs_location4 { struct fs_location4 {
utf8str_cis server<>; utf8str_cis server<>;
pathname4 rootpath; pathname4 rootpath;
}; };
]]></sourcecode> ]]></sourcecode>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct fs_locations4 { struct fs_locations4 {
pathname4 fs_root; pathname4 fs_root;
fs_location4 locations<>; fs_location4 locations<>;
}; };
]]></sourcecode> ]]></sourcecode>
<t> <t>
The fs_location4 data type is used to represent the location of a The fs_location4 data type is used to represent the location of a
file system by providing a server name and the path to the root file system by providing a server name and the path to the root
of the file system within that server's namespace. of the file system within that server's namespace.
When a set of servers have corresponding file systems at the When a set of servers have corresponding file systems at the
skipping to change at line 19015 skipping to change at line 18575
The fs_locations_info attribute consists of a root The fs_locations_info attribute consists of a root
pathname (fli_fs_root, just like fs_root in the pathname (fli_fs_root, just like fs_root in the
fs_locations attribute), together with an array of fs_locations attribute), together with an array of
fs_location_item4 structures. The fs_location_item4 fs_location_item4 structures. The fs_location_item4
structures in turn consist of a root pathname structures in turn consist of a root pathname
(fli_rootpath) together with an array (fli_entries) (fli_rootpath) together with an array (fli_entries)
of elements of data type fs_locations_server4, of elements of data type fs_locations_server4,
all defined as follows. all defined as follows.
</t> </t>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
/* /*
* Defines an individual server access path * Defines an individual server access path
*/ */
struct fs_locations_server4 { struct fs_locations_server4 {
int32_t fls_currency; int32_t fls_currency;
opaque fls_info<>; opaque fls_info<>;
utf8str_cis fls_server; utf8str_cis fls_server;
}; };
/* /*
skipping to change at line 19109 skipping to change at line 18669
<t> <t>
The data presented in the fs_locations_info attribute may be obtained The data presented in the fs_locations_info attribute may be obtained
by the server in any number of ways, including specification by by the server in any number of ways, including specification by
the administrator or by current protocols for transferring data the administrator or by current protocols for transferring data
among replicas and protocols not yet developed. NFSv4.1 only defines among replicas and protocols not yet developed. NFSv4.1 only defines
how this information is presented by the server to how this information is presented by the server to
the client. the client.
</t> </t>
<section anchor="SEC11-fsli-server" numbered="true" toc="default"> <section anchor="SEC11-fsli-server" numbered="true" toc="default">
<name>The fs_locations_server4 Structure</name> <name>The fs_locations_server4 Structure</name>
<!-- [rfced] In Section 11.17.1, should "flinfo" be instead
"fls_info" in the following sentence?
Current:
Note that both of these items (i.e., fls_currency and flinfo)
specify attributes of the file system replica and should not be
different when there are multiple fs_locations_server4 structures,
each specifying a network path to the chosen replica, for the same
replica.
<t> <t>
The fs_locations_server4 structure consists of the following items The fs_locations_server4 structure consists of the following items
in addition to the fls_server field, which specifies a network in addition to the fls_server field, which specifies a network
address or set of addresses to be used to access the specified file address or set of addresses to be used to access the specified file
system. Note that both of these items (i.e., fls_currency and flinfo) system. Note that both of these items (i.e., fls_currency and
fls_info)
specify attributes of the specify attributes of the
file system replica and should not be different when there are file system replica and should not be different when there are
multiple fs_locations_server4 structures, each multiple fs_locations_server4 structures, each
specifying a network path to the chosen replica, for the same specifying a network path to the chosen replica, for the same
replica. replica.
</t> </t>
<t> <t>
When these values are different in two fs_locations_server4 structures, When these values are different in two fs_locations_server4 structures,
a client has no basis for choosing one over the other and is best off a client has no basis for choosing one over the other and is best off
simply ignoring both entries, whether these entries apply to migration simply ignoring both entries, whether these entries apply to migration
skipping to change at line 19733 skipping to change at line 19284
</section> </section>
</section> </section>
<section anchor="fs_status" numbered="true" toc="default"> <section anchor="fs_status" numbered="true" toc="default">
<name>The Attribute fs_status</name> <name>The Attribute fs_status</name>
<t> <t>
In an environment in which multiple copies of the same basic set of In an environment in which multiple copies of the same basic set of
data are available, information regarding the particular source of data are available, information regarding the particular source of
such data and the relationships among different copies can be very such data and the relationships among different copies can be very
helpful in providing consistent data to applications. helpful in providing consistent data to applications.
</t> </t>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
enum fs4_status_type { enum fs4_status_type {
STATUS4_FIXED = 1, STATUS4_FIXED = 1,
STATUS4_UPDATED = 2, STATUS4_UPDATED = 2,
STATUS4_VERSIONED = 3, STATUS4_VERSIONED = 3,
STATUS4_WRITABLE = 4, STATUS4_WRITABLE = 4,
STATUS4_REFERRAL = 5 STATUS4_REFERRAL = 5
}; };
struct fs4_status { struct fs4_status {
bool fss_absent; bool fss_absent;
skipping to change at line 19937 skipping to change at line 19488
order (and the elements should form a total order within the order (and the elements should form a total order within the
partial order) and partial order) and
using the last. using the last.
The client may then, when switching among The client may then, when switching among
file system instances, decline to use an instance that does not have file system instances, decline to use an instance that does not have
an fss_type of STATUS4_VERSIONED or whose fss_version field is earlier than the an fss_type of STATUS4_VERSIONED or whose fss_version field is earlier than the
last one obtained from the predecessor file system instance. last one obtained from the predecessor file system instance.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- [auth] Copyright (C) The IETF Trust (2007-2008) -->
<!-- [auth] Copyright (C) The Internet Society (2006) -->
<section anchor="pnfs" numbered="true" toc="default"> <section anchor="pnfs" numbered="true" toc="default">
<name>Parallel NFS (pNFS)</name> <name>Parallel NFS (pNFS)</name>
<section anchor="pnfs_intro" numbered="true" toc="default"> <section anchor="pnfs_intro" numbered="true" toc="default">
<name>Introduction</name> <name>Introduction</name>
<t> <t>
pNFS is an <bcp14>OPTIONAL</bcp14> feature within NFSv4.1; the pNFS feature pNFS is an <bcp14>OPTIONAL</bcp14> feature within NFSv4.1; the pNFS feature
set allows direct client access to the storage devices containing set allows direct client access to the storage devices containing
file data. When file data for a single NFSv4 server is stored on file data. When file data for a single NFSv4 server is stored on
multiple and/or higher-throughput storage devices (by comparison to multiple and/or higher-throughput storage devices (by comparison to
the server's throughput capability), the result can be significantly the server's throughput capability), the result can be significantly
skipping to change at line 20095 skipping to change at line 19643
The NFSv4.1 pNFS feature has been structured to allow for a variety The NFSv4.1 pNFS feature has been structured to allow for a variety
of storage protocols to be defined and used. of storage protocols to be defined and used.
One example storage protocol is NFSv4.1 itself (as documented in One example storage protocol is NFSv4.1 itself (as documented in
<xref target="file_layout_type" format="default"/>). Other options for the storage protocol <xref target="file_layout_type" format="default"/>). Other options for the storage protocol
are described elsewhere and include: are described elsewhere and include:
</t> </t>
<ul spacing="normal"> <ul spacing="normal">
<li> <li>
Block/volume protocols such as Internet SCSI (iSCSI) Block/volume protocols such as Internet SCSI (iSCSI)
<xref target="RFC3720" format="default"/> and FCP <xref target="FCP-2" format="default"/>. The block/volume <xref target="RFC7143" format="default"/> and FCP <xref target="FCP-2" format="default"/>. The block/volume
protocol support can be independent of the addressing structure protocol support can be independent of the addressing structure
of the block/volume protocol used, allowing more than one of the block/volume protocol used, allowing more than one
protocol to access the same file data and enabling extensibility protocol to access the same file data and enabling extensibility
to other block/volume protocols. See to other block/volume protocols. See
<xref target="RFC5663" format="default"/> for a layout <xref target="RFC5663" format="default"/> for a layout
specification that specification that
allows pNFS to use block/volume storage protocols. allows pNFS to use block/volume storage protocols.
</li> </li>
<li> <li>
Object protocols such as OSD over iSCSI or Fibre Channel <xref target="OSD-T10" format="default"/>. See Object protocols such as OSD over iSCSI or Fibre Channel <xref target="OSD-T10" format="default"/>. See
skipping to change at line 20778 skipping to change at line 20326
which reserved or allocated blocks the client used or did not use. which reserved or allocated blocks the client used or did not use.
The content of loca_layoutupdate (field lou_body) need not be the The content of loca_layoutupdate (field lou_body) need not be the
same layout-type-specific content returned by LAYOUTGET (<xref target="OP_LAYOUTGET_RESULT" format="default"/>) in the loc_body field of the same layout-type-specific content returned by LAYOUTGET (<xref target="OP_LAYOUTGET_RESULT" format="default"/>) in the loc_body field of the
lo_content field of the logr_layout field. lo_content field of the logr_layout field.
The content of The content of
loca_layoutupdate is defined by the layout type specification and is loca_layoutupdate is defined by the layout type specification and is
opaque to LAYOUTCOMMIT. opaque to LAYOUTCOMMIT.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] Layout Semantics -->
<section anchor="recalling_layout" numbered="true" toc="default"> <section anchor="recalling_layout" numbered="true" toc="default">
<name>Recalling a Layout</name> <name>Recalling a Layout</name>
<t> <t>
Since a layout protects a client's access to a file via a direct Since a layout protects a client's access to a file via a direct
client-storage-device path, a layout need only be recalled when it client-storage-device path, a layout need only be recalled when it
is semantically unable to serve this function. Typically, this is semantically unable to serve this function. Typically, this
occurs when the layout no longer encapsulates the true location of occurs when the layout no longer encapsulates the true location of
the file over the byte-range it represents. Any operation or the file over the byte-range it represents. Any operation or
action, such as server-driven restriping or load balancing, that action, such as server-driven restriping or load balancing, that
skipping to change at line 21790 skipping to change at line 21337
of the metadata server.) For handling of access control specific to of the metadata server.) For handling of access control specific to
a layout, the reader should examine the layout specification, such as a layout, the reader should examine the layout specification, such as
the <xref target="file_layout_type" format="default">NFSv4.1/file-based layout</xref> the <xref target="file_layout_type" format="default">NFSv4.1/file-based layout</xref>
of this document, the <xref target="RFC5663" format="default">blocks of this document, the <xref target="RFC5663" format="default">blocks
layout</xref>, and <xref target="RFC5664" format="default">objects layout</xref>, and <xref target="RFC5664" format="default">objects
layout</xref>. layout</xref>.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- [auth] Copyright (C) The IETF Trust (2007-2008) -->
<!-- [auth] Copyright (C) The Internet Society (2006) -->
<section anchor="file_layout_type" numbered="true" toc="default"> <section anchor="file_layout_type" numbered="true" toc="default">
<name>NFSv4.1 as a Storage Protocol in pNFS: the File Layout Type</name> <name>NFSv4.1 as a Storage Protocol in pNFS: the File Layout Type</name>
<t> <t>
This section describes the semantics and format of NFSv4.1 file-based This section describes the semantics and format of NFSv4.1 file-based
layouts for pNFS. layouts for pNFS.
NFSv4.1 file-based layouts use the LAYOUT4_NFSV4_1_FILES layout type. NFSv4.1 file-based layouts use the LAYOUT4_NFSV4_1_FILES layout type.
The LAYOUT4_NFSV4_1_FILES type defines The LAYOUT4_NFSV4_1_FILES type defines
striping data across multiple NFSv4.1 data servers. striping data across multiple NFSv4.1 data servers.
</t> </t>
<section anchor="pnfs_session_stuff" numbered="true" toc="default"> <section anchor="pnfs_session_stuff" numbered="true" toc="default">
skipping to change at line 22064 skipping to change at line 21608
</t> </t>
<t> <t>
A pattern may have more stripe units than data servers. A pattern may have more stripe units than data servers.
If so, some data servers will have more than one stripe unit If so, some data servers will have more than one stripe unit
per stripe. A data server that has multiple stripe per stripe. A data server that has multiple stripe
units per stripe <bcp14>MAY</bcp14> store each unit in a different data file (and units per stripe <bcp14>MAY</bcp14> store each unit in a different data file (and
depending on the implementation, will possibly assign a unique data depending on the implementation, will possibly assign a unique data
filehandle to each data file). filehandle to each data file).
</t> </t>
</section> </section>
<!-- [auth] "File Striping Definitions" "file_layout_definitions" -->
<section anchor="file_data_types" numbered="true" toc="default"> <section anchor="file_data_types" numbered="true" toc="default">
<name>File Layout Data Types</name> <name>File Layout Data Types</name>
<t> <t>
The high level NFSv4.1 layout types are The high level NFSv4.1 layout types are
nfsv4_1_file_layouthint4, nfsv4_1_file_layouthint4,
nfsv4_1_file_layout_ds_addr4, nfsv4_1_file_layout_ds_addr4,
and nfsv4_1_file_layout4. and nfsv4_1_file_layout4.
</t> </t>
<t> <t>
The SETATTR operation supports a layout hint attribute The SETATTR operation supports a layout hint attribute
(<xref target="attrdef_layout_hint" format="default"/>). (<xref target="attrdef_layout_hint" format="default"/>).
When the client sets a layout hint (data type layouthint4) with When the client sets a layout hint (data type layouthint4) with
a layout type of LAYOUT4_NFSV4_1_FILES (the loh_type field), a layout type of LAYOUT4_NFSV4_1_FILES (the loh_type field),
the loh_body field contains a value of data type the loh_body field contains a value of data type
nfsv4_1_file_layouthint4. nfsv4_1_file_layouthint4.
</t> </t>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
const NFL4_UFLG_MASK = 0x0000003F; const NFL4_UFLG_MASK = 0x0000003F;
const NFL4_UFLG_DENSE = 0x00000001; const NFL4_UFLG_DENSE = 0x00000001;
const NFL4_UFLG_COMMIT_THRU_MDS = 0x00000002; const NFL4_UFLG_COMMIT_THRU_MDS = 0x00000002;
const NFL4_UFLG_STRIPE_UNIT_SIZE_MASK const NFL4_UFLG_STRIPE_UNIT_SIZE_MASK
= 0xFFFFFFC0; = 0xFFFFFFC0;
typedef uint32_t nfl_util4; typedef uint32_t nfl_util4;
enum filelayout_hint_care4 { enum filelayout_hint_care4 {
NFLH4_CARE_DENSE = NFL4_UFLG_DENSE, NFLH4_CARE_DENSE = NFL4_UFLG_DENSE,
skipping to change at line 22153 skipping to change at line 21696
contains a value of data type nfsv4_1_file_layout4. contains a value of data type nfsv4_1_file_layout4.
Among other content, nfsv4_1_file_layout4 has a storage Among other content, nfsv4_1_file_layout4 has a storage
device ID (field nfl_deviceid) of data type device ID (field nfl_deviceid) of data type
deviceid4. deviceid4.
The GETDEVICEINFO operation maps a device ID to The GETDEVICEINFO operation maps a device ID to
a storage device address (type device_addr4). When GETDEVICEINFO a storage device address (type device_addr4). When GETDEVICEINFO
returns a device address with a layout type of LAYOUT4_NFSV4_1_FILES returns a device address with a layout type of LAYOUT4_NFSV4_1_FILES
(the da_layout_type field), the da_addr_body field contains (the da_layout_type field), the da_addr_body field contains
a value of data type nfsv4_1_file_layout_ds_addr4. a value of data type nfsv4_1_file_layout_ds_addr4.
</t> </t>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
typedef netaddr4 multipath_list4<>; typedef netaddr4 multipath_list4<>;
/* /*
* Encoded in the da_addr_body field of * Encoded in the da_addr_body field of
* data type device_addr4: * data type device_addr4:
*/ */
struct nfsv4_1_file_layout_ds_addr4 { struct nfsv4_1_file_layout_ds_addr4 {
uint32_t nflda_stripe_indices<>; uint32_t nflda_stripe_indices<>;
multipath_list4 nflda_multipath_ds_list<>; multipath_list4 nflda_multipath_ds_list<>;
}; };
skipping to change at line 22187 skipping to change at line 21730
<li> <li>
nflda_stripe_indices: An array of indices used to index into nflda_stripe_indices: An array of indices used to index into
nflda_multipath_ds_list. The value of each element of nflda_stripe_indices <bcp14>MUST</bcp14> nflda_multipath_ds_list. The value of each element of nflda_stripe_indices <bcp14>MUST</bcp14>
be less than the number of elements in nflda_multipath_ds_list. be less than the number of elements in nflda_multipath_ds_list.
Each element of nflda_multipath_ds_list <bcp14>SHOULD</bcp14> be referred to by one Each element of nflda_multipath_ds_list <bcp14>SHOULD</bcp14> be referred to by one
or more elements of nflda_stripe_indices. or more elements of nflda_stripe_indices.
The number of elements in The number of elements in
nflda_stripe_indices is always equal to the stripe count. nflda_stripe_indices is always equal to the stripe count.
</li> </li>
</ol> </ol>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
/* /*
* Encoded in the loc_body field of * Encoded in the loc_body field of
* data type layout_content4: * data type layout_content4:
*/ */
struct nfsv4_1_file_layout4 { struct nfsv4_1_file_layout4 {
deviceid4 nfl_deviceid; deviceid4 nfl_deviceid;
nfl_util4 nfl_util; nfl_util4 nfl_util;
uint32_t nfl_first_stripe_index; uint32_t nfl_first_stripe_index;
offset4 nfl_pattern_offset; offset4 nfl_pattern_offset;
nfs_fh4 nfl_fh_list<>; nfs_fh4 nfl_fh_list<>;
skipping to change at line 22344 skipping to change at line 21887
</ul> </ul>
</li> </li>
</ol> </ol>
<t> <t>
The details on the interpretation of the layout are in The details on the interpretation of the layout are in
<xref target="file_layout_interpret" format="default"/>. <xref target="file_layout_interpret" format="default"/>.
</t> </t>
</section> </section>
<!-- [auth] "File Layout Data Types" "file_data_types" -->
<section anchor="file_layout_interpret" numbered="true" toc="default"> <section anchor="file_layout_interpret" numbered="true" toc="default">
<name>Interpreting the File Layout</name> <name>Interpreting the File Layout</name>
<section anchor="SUi" numbered="true" toc="default"> <section anchor="SUi" numbered="true" toc="default">
<name>Determining the Stripe Unit Number</name> <name>Determining the Stripe Unit Number</name>
<t> <t>
To find the stripe unit number that corresponds to the client's To find the stripe unit number that corresponds to the client's
logical file offset, the pattern offset will also be used. The logical file offset, the pattern offset will also be used. The
i'th stripe unit (SUi) is: i'th stripe unit (SUi) is:
</t> </t>
<sourcecode type=""><![CDATA[ <sourcecode type="pseudocode"><![CDATA[
relative_offset = file_offset - nfl_pattern_offset; relative_offset = file_offset - nfl_pattern_offset;
SUi = floor(relative_offset / stripe_unit_size);]]></sourcecode> SUi = floor(relative_offset / stripe_unit_size);]]></sourcecode>
</section> </section>
<section numbered="true" toc="default"> <section numbered="true" toc="default">
<name>Interpreting the File Layout Using Sparse Packing</name> <name>Interpreting the File Layout Using Sparse Packing</name>
<t> <t>
When sparse packing is used, the algorithm for determining the filehandle and set When sparse packing is used, the algorithm for determining the filehandle and set
of data-server network addresses to write stripe unit i of data-server network addresses to write stripe unit i
(SUi) to is: (SUi) to is:
</t> </t>
<sourcecode type=""><![CDATA[ <sourcecode type="pseudocode"><![CDATA[
stripe_count = number of elements in nflda_stripe_indices; stripe_count = number of elements in nflda_stripe_indices;
j = (SUi + nfl_first_stripe_index) % stripe_count; j = (SUi + nfl_first_stripe_index) % stripe_count;
idx = nflda_stripe_indices[j]; idx = nflda_stripe_indices[j];
fh_count = number of elements in nfl_fh_list; fh_count = number of elements in nfl_fh_list;
ds_count = number of elements in nflda_multipath_ds_list; ds_count = number of elements in nflda_multipath_ds_list;
switch (fh_count) { switch (fh_count) {
skipping to change at line 22615 skipping to change at line 22157
</tr> </tr>
</tbody> </tbody>
</table> </table>
</section> </section>
<section numbered="true" toc="default"> <section numbered="true" toc="default">
<name>Interpreting the File Layout Using Dense Packing</name> <name>Interpreting the File Layout Using Dense Packing</name>
<t> <t>
When dense packing is used, the algorithm for determining the filehandle and set When dense packing is used, the algorithm for determining the filehandle and set
of data server network addresses to write stripe unit i (SUi) to is: of data server network addresses to write stripe unit i (SUi) to is:
</t> </t>
<sourcecode type=""><![CDATA[ <sourcecode type="pseudocode"><![CDATA[
stripe_count = number of elements in nflda_stripe_indices; stripe_count = number of elements in nflda_stripe_indices;
j = (SUi + nfl_first_stripe_index) % stripe_count; j = (SUi + nfl_first_stripe_index) % stripe_count;
idx = nflda_stripe_indices[j]; idx = nflda_stripe_indices[j];
fh_count = number of elements in nfl_fh_list; fh_count = number of elements in nfl_fh_list;
ds_count = number of elements in nflda_multipath_ds_list; ds_count = number of elements in nflda_multipath_ds_list;
switch (fh_count) { switch (fh_count) {
skipping to change at line 22926 skipping to change at line 22468
<t> <t>
Because dense packing does not leave holes on the data servers, Because dense packing does not leave holes on the data servers,
the pNFS client is allowed to write to any offset of any data file of the pNFS client is allowed to write to any offset of any data file of
any data server in the stripe. Thus, the data servers need not know any data server in the stripe. Thus, the data servers need not know
the file's striping pattern. the file's striping pattern.
</t> </t>
<t> <t>
The calculation to determine the byte offset within the data file The calculation to determine the byte offset within the data file
for dense data server layouts is: for dense data server layouts is:
</t> </t>
<sourcecode type=""><![CDATA[ <sourcecode type="pseudocode"><![CDATA[
stripe_width = stripe_unit_size * N; stripe_width = stripe_unit_size * N;
where N = number of elements in nflda_stripe_indices. where N = number of elements in nflda_stripe_indices.
relative_offset = file_offset - nfl_pattern_offset; relative_offset = file_offset - nfl_pattern_offset;
data_file_offset = floor(relative_offset / stripe_width) data_file_offset = floor(relative_offset / stripe_width)
* stripe_unit_size * stripe_unit_size
+ relative_offset % stripe_unit_size]]></sourcecode> + relative_offset % stripe_unit_size]]></sourcecode>
<t> <t>
If dense packing is being used, and a data server appears If dense packing is being used, and a data server appears
skipping to change at line 22953 skipping to change at line 22495
also served by data server 2. Unless data server 2 has also served by data server 2. Unless data server 2 has
two filehandles (each referring to a different data two filehandles (each referring to a different data
file), then, for example, a write to logical stripe file), then, for example, a write to logical stripe
unit 1 overwrites the write to logical stripe unit 2 unit 1 overwrites the write to logical stripe unit 2
because both logical stripe units are located in the because both logical stripe units are located in the
same stripe unit (0) of data server 2. same stripe unit (0) of data server 2.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] "Interpreting the File Layout" anchor="file_layout_interpret" -->
<section anchor="file_multipath" numbered="true" toc="default"> <section anchor="file_multipath" numbered="true" toc="default">
<name>Data Server Multipathing</name> <name>Data Server Multipathing</name>
<t> <t>
The NFSv4.1 file layout supports multipathing to The NFSv4.1 file layout supports multipathing to
multiple data server addresses. multiple data server addresses.
Data-server-level multipathing is used for Data-server-level multipathing is used for
bandwidth scaling via trunking (<xref target="Trunking" format="default"/>) and for higher availability of use in the case of bandwidth scaling via trunking (<xref target="Trunking" format="default"/>) and for higher availability of use in the case of
a data-server failure. Multipathing allows the client a data-server failure. Multipathing allows the client
to switch to another data server address which may be that to switch to another data server address which may be that
skipping to change at line 23410 skipping to change at line 22951
<name>File Attributes</name> <name>File Attributes</name>
<t> <t>
Since the SETATTR operation has the ability to modify state that is Since the SETATTR operation has the ability to modify state that is
visible on both the metadata and data servers (e.g., the size), visible on both the metadata and data servers (e.g., the size),
care must be taken to ensure that the resultant state across the care must be taken to ensure that the resultant state across the
set of data servers is consistent, especially when truncating or set of data servers is consistent, especially when truncating or
growing the file. growing the file.
</t> </t>
<t> <t>
As described earlier, the LAYOUTCOMMIT operation is used to ensure As described earlier, the LAYOUTCOMMIT operation is used to ensure
that the metadata is synchronized with changes made to the data servers. For the NFSv4.1‑based data storage protocol, that the metadata is synchronized with changes made to the data servers.
For the NFSv4.1-based data storage protocol,
it is necessary to re-synchronize it is necessary to re-synchronize
state such as the size attribute, and the setting of mtime/change/atime. state such as the size attribute, and the setting of mtime/change/atime.
See <xref target="committing_layout" format="default"/> for a full See <xref target="committing_layout" format="default"/> for a full
description of the semantics regarding LAYOUTCOMMIT and description of the semantics regarding LAYOUTCOMMIT and
attribute synchronization. It should be noted that by attribute synchronization. It should be noted that by
using an NFSv4.1-based layout type, it is possible to using an NFSv4.1-based layout type, it is possible to
synchronize this state before LAYOUTCOMMIT occurs. For synchronize this state before LAYOUTCOMMIT occurs. For
example, the control protocol can be used to query the example, the control protocol can be used to query the
attributes present on the data servers. attributes present on the data servers.
</t> </t>
skipping to change at line 23601 skipping to change at line 23143
consistent across on the pNFS server. consistent across on the pNFS server.
</t> </t>
<t> <t>
If an NFSv4.1 implementation supports If an NFSv4.1 implementation supports
pNFS and supports NFSv4.1 file layouts, then the pNFS and supports NFSv4.1 file layouts, then the
implementation <bcp14>MUST</bcp14> support the SECINFO_NO_NAME operation on both implementation <bcp14>MUST</bcp14> support the SECINFO_NO_NAME operation on both
the metadata and data servers. the metadata and data servers.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- [auth] Copyright (C) The IETF Trust (2007-2008) -->
<!-- [auth] Copyright (C) The Internet Society (2006) -->
<section anchor="internationalization" numbered="true" toc="default"> <section anchor="internationalization" numbered="true" toc="default">
<name>Internationalization</name> <name>Internationalization</name>
<t> <t>
The primary issue in which NFSv4.1 needs to deal with The primary issue in which NFSv4.1 needs to deal with
internationalization, or I18N, is with respect to file names and other internationalization, or I18N, is with respect to file names and other
strings as used within the protocol. The choice of string strings as used within the protocol. The choice of string
representation must allow reasonable name/string access to clients representation must allow reasonable name/string access to clients
that use various languages. The UTF-8 encoding of the UCS (Universal that use various languages. The UTF-8 encoding of the UCS (Universal
Multiple-Octet Coded Character Set) as defined Multiple-Octet Coded Character Set) as defined
by <xref target="ISO.10646-1.1993" format="default">ISO10646</xref> allows for this type by <xref target="ISO.10646-1.1993" format="default">ISO10646</xref> allows for this type
skipping to change at line 23913 skipping to change at line 23452
<section toc="exclude" numbered="true"> <section toc="exclude" numbered="true">
<name>Bidirectional Output for nfs4_mixed_prep</name> <name>Bidirectional Output for nfs4_mixed_prep</name>
<t> <t>
The nfs4_mixed_prep profile specifies checking bidirectional strings The nfs4_mixed_prep profile specifies checking bidirectional strings
as described in stringprep's Section <xref target="RFC3454" sectionFormat="bare" section="6"/>. as described in stringprep's Section <xref target="RFC3454" sectionFormat="bare" section="6"/>.
</t> </t>
</section> </section>
</section> </section>
<section anchor="utf8_caps" numbered="true" toc="default"> <section anchor="utf8_caps" numbered="true" toc="default">
<name>UTF-8 Capabilities</name> <name>UTF-8 Capabilities</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
const FSCHARSET_CAP4_CONTAINS_NON_UTF8 = 0x1; const FSCHARSET_CAP4_CONTAINS_NON_UTF8 = 0x1;
const FSCHARSET_CAP4_ALLOWS_ONLY_UTF8 = 0x2; const FSCHARSET_CAP4_ALLOWS_ONLY_UTF8 = 0x2;
typedef uint32_t fs_charset_cap4;]]></sourcecode> typedef uint32_t fs_charset_cap4;]]></sourcecode>
<t> <t>
Because some operating environments and file systems do Because some operating environments and file systems do
not enforce character set encodings, NFSv4.1 supports the not enforce character set encodings, NFSv4.1 supports the
fs_charset_cap attribute (<xref target="attrdef_fs_charset_cap" format="default"/>) fs_charset_cap attribute (<xref target="attrdef_fs_charset_cap" format="default"/>)
that indicates to the client a file system's UTF-8 capabilities. that indicates to the client a file system's UTF-8 capabilities.
The attribute is an integer containing a pair of flags. The attribute is an integer containing a pair of flags.
skipping to change at line 23965 skipping to change at line 23504
Where a UTF-8 string is used as a file name, and the file system (while Where a UTF-8 string is used as a file name, and the file system (while
supporting all of the characters within the name) does not allow that supporting all of the characters within the name) does not allow that
particular name to be used, the server should return the error <xref target="error_definitions" format="default">NFS4ERR_BADNAME</xref>. This includes particular name to be used, the server should return the error <xref target="error_definitions" format="default">NFS4ERR_BADNAME</xref>. This includes
situations in which the server file system imposes a normalization situations in which the server file system imposes a normalization
constraint on name strings, but will also include such situations as constraint on name strings, but will also include such situations as
file system prohibitions of "." and ".." as file names for certain file system prohibitions of "." and ".." as file names for certain
operations, and other such constraints. operations, and other such constraints.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- [auth] Copyright (C) The IETF Trust (2007-2008) -->
<!-- [auth] Copyright (C) The Internet Society (2006) -->
<section numbered="true" toc="default"> <section numbered="true" toc="default">
<name>Error Values</name> <name>Error Values</name>
<t> <t>
NFS error numbers are assigned to failed operations within a NFS error numbers are assigned to failed operations within a
Compound (COMPOUND or CB_COMPOUND) request. A Compound request Compound (COMPOUND or CB_COMPOUND) request. A Compound request
contains a number of NFS operations that have their results contains a number of NFS operations that have their results
encoded in sequence in a Compound reply. The results of successful encoded in sequence in a Compound reply. The results of successful
operations will consist of an NFS4_OK status followed by the operations will consist of an NFS4_OK status followed by the
encoded results of the operation. If an NFS operation fails, an encoded results of the operation. If an NFS operation fails, an
skipping to change at line 24670 skipping to change at line 24206
and returned makes processing this request in a timely fashion impossible. and returned makes processing this request in a timely fashion impossible.
</li> </li>
<li> <li>
A request is being performed on a session being migrated A request is being performed on a session being migrated
from another server as described in <xref target="SEC11-XS-session" format="default"/>, from another server as described in <xref target="SEC11-XS-session" format="default"/>,
and the lack of full information about the and the lack of full information about the
state of the session on the source makes it impossible state of the session on the source makes it impossible
to process the request immediately. to process the request immediately.
</li> </li>
</ul> </ul>
<!-- [rfced] In Section 15.1.1.3, the term "replay cache" is
used. Should it instead be "reply cache"?
For example:
Because of the need to avoid spurious
reissues of non-idempotent operations and to avoid acting in response
to NFS4ERR_DELAY errors returned on responses returned from the
replier's replay cache, integration with the session-provided replay
cache is necessary.
<!-- [rfced] In Section 15.1.1.3, we're having difficulty parsing
these sentences. Is this a response to a response, or a response
to a response to a response? That is, are the errors found in
responses, or are they found in responses to responses?
This is also the first use of the term replay cache.
Current:
Because of the need to avoid spurious reissues of non-idempotent
operations and to avoid acting in response to NFS4ERR_DELAY
errors returned on responses returned from the replier's replay
cache, integration with the session-provided replay cache is
necessary.
...
In this case, the replier MUST avoid returning a response
containing NFS4ERR_DELAY as the response to SEQUENCE solely on
the basis of its presence in the replay cache.
<t> <t>
In such cases, returning the error NFS4ERR_DELAY allows In such cases, returning the error NFS4ERR_DELAY allows
necessary preparatory operations to proceed without necessary preparatory operations to proceed without
holding up requester resources such as a session slot. holding up requester resources such as a session slot.
After delaying for period of time, the client can After delaying for period of time, the client can
then re-send the operation in question, often as part then re-send the operation in question, often as part
of a nearly identical request. Because of the need to avoid of a nearly identical request. Because of the need to avoid
spurious reissues of non-idempotent operations and to avoid spurious reissues of non-idempotent operations and to avoid
acting in response to NFS4ERR_DELAY errors returned on responses acting in response to NFS4ERR_DELAY errors returned on responses
returned from the replier's replay cache, returned from the replier's reply cache,
integration with the session-provided replay cache is necessary. integration with the session-provided reply cache is necessary.
There are a number of cases to deal with, each of which requires There are a number of cases to deal with, each of which requires
different sorts of handling by the requester and replier: different sorts of handling by the requester and replier:
</t> </t>
<ul spacing="normal"> <ul spacing="normal">
<li> <li>
If NFS4ERR_DELAY is returned on a SEQUENCE operation, the If NFS4ERR_DELAY is returned on a SEQUENCE operation, the
request is retried in full with the SEQUENCE operation request is retried in full with the SEQUENCE operation
containing the same slot and sequence values. In this case, containing the same slot and sequence values. In this case,
the replier <bcp14>MUST</bcp14> avoid returning a response containing the replier <bcp14>MUST</bcp14> avoid returning a response
NFS4ERR_DELAY as the response to SEQUENCE solely on the basis containing NFS4ERR_DELAY as the response to SEQUENCE solely
of its presence in the replay cache. If the replier did this, because an earlier instance of the same request returned that error
and it was stored in the reply cache. If the replier did this,
the retries would not be effective as there would be no the retries would not be effective as there would be no
opportunity for the replier to see whether the condition that opportunity for the replier to see whether the condition that
generated the NFS4ERR_DELAY had been rectified during the generated the NFS4ERR_DELAY had been rectified during the
interim between the original request and the retry. interim between the original request and the retry.
</li> </li>
<li> <li>
If NFS4ERR_DELAY is returned on an operation other than SEQUENCE If NFS4ERR_DELAY is returned on an operation other than SEQUENCE
that validly appears as the first operation of a request, the handling that validly appears as the first operation of a request, the handling
is similar. The request can be retried in full without modification. is similar. The request can be retried in full without modification.
In this case as well, In this case as well,
the replier <bcp14>MUST</bcp14> avoid returning a response containing the replier <bcp14>MUST</bcp14> avoid returning a response containing
NFS4ERR_DELAY as the response to an initial operation of a request NFS4ERR_DELAY as the response to an initial operation of a request
solely on the basis solely on the basis
of its presence in the replay cache. If the replier did this, of its presence in the reply cache. If the replier did this,
the retries would not be effective as there would be no the retries would not be effective as there would be no
opportunity for the replier to see whether the condition that opportunity for the replier to see whether the condition that
generated the NFS4ERR_DELAY had been rectified during the generated the NFS4ERR_DELAY had been rectified during the
interim between the original request and the retry. interim between the original request and the retry.
</li> </li>
<!-- [rfced] In Section 15.1.1.2, the sentence below contains
the only instance of "bin id". Should it be "slot ID"?
Current:
If NFS4ERR_DELAY is returned on an operation other than the first
in the request, the request when retried MUST contain a SEQUENCE
operation that is different than the original one, with either
the bin id or the sequence value different from that in the
original request.
<li> <li>
If NFS4ERR_DELAY is returned on an operation other than the first If NFS4ERR_DELAY is returned on an operation other than the first
in the request, the request when retried <bcp14>MUST</bcp14> contain a SEQUENCE in the request, the request when retried <bcp14>MUST</bcp14> contain a SEQUENCE
operation that is different than the original one, with either operation that is different than the original one, with either
the bin id or the sequence value different from that in the original the slot ID or the sequence value different from that in the original
request. Because requesters do this, there is no need for the request. Because requesters do this, there is no need for the
replier to take special care to avoid returning an replier to take special care to avoid returning an
NFS4ERR_DELAY error obtained from the replay cache. When no non-idempotent NFS4ERR_DELAY error obtained from the reply cache. When no non-idempotent
operations have been processed before the NFS4ERR_DELAY was returned, operations have been processed before the NFS4ERR_DELAY was returned,
the requester should retry the request in full, with the only the requester should retry the request in full, with the only
difference from the original request being the modification to the difference from the original request being the modification to the
slot ID or sequence value in the reissued SEQUENCE operation. slot ID or sequence value in the reissued SEQUENCE operation.
</li> </li>
<li> <li>
<t> <t>
When NFS4ERR_DELAY is returned on an operation other than the first When NFS4ERR_DELAY is returned on an operation other than the first
within a request and there has been a non-idempotent operation within a request and there has been a non-idempotent operation
processed before the NFS4ERR_DELAY was returned, reissuing the request as is normally processed before the NFS4ERR_DELAY was returned, reissuing the request as is normally
skipping to change at line 25076 skipping to change at line 24574
<t> <t>
An attempt was made to create an object with an inappropriate An attempt was made to create an object with an inappropriate
type specified to CREATE. This may be because the type type specified to CREATE. This may be because the type
is undefined, because the type is not supported by the is undefined, because the type is not supported by the
server, or because the type is not intended to be created by CREATE server, or because the type is not intended to be created by CREATE
(such as a regular file or named attribute, for (such as a regular file or named attribute, for
which OPEN is used to do the file creation). which OPEN is used to do the file creation).
</t> </t>
</section> </section>
<section anchor="err_DQUOT" numbered="true" toc="default"> <section anchor="err_DQUOT" numbered="true" toc="default">
<name>NFS4ERR_DQUOT (Error Code 19)</name> <name>NFS4ERR_DQUOT (Error Code 69)</name>
<t> <t>
Resource (quota) hard limit exceeded. The user's resource Resource (quota) hard limit exceeded. The user's resource
limit on the server has been exceeded. limit on the server has been exceeded.
</t> </t>
</section> </section>
<section anchor="err_EXIST" numbered="true" toc="default"> <section anchor="err_EXIST" numbered="true" toc="default">
<name>NFS4ERR_EXIST (Error Code 17)</name> <name>NFS4ERR_EXIST (Error Code 17)</name>
<t> <t>
A file of the specified target name (when creating, renaming, A file of the specified target name (when creating, renaming,
or linking) already exists. or linking) already exists.
skipping to change at line 25899 skipping to change at line 25397
<t> <t>
A stateid generated by an earlier server instance was A stateid generated by an earlier server instance was
used. This error is moot in NFSv4.1 because all operations that used. This error is moot in NFSv4.1 because all operations that
take a stateid <bcp14>MUST</bcp14> be preceded by the SEQUENCE operation, take a stateid <bcp14>MUST</bcp14> be preceded by the SEQUENCE operation,
and the earlier server instance is detected by the session and the earlier server instance is detected by the session
infrastructure that supports SEQUENCE. infrastructure that supports SEQUENCE.
</t> </t>
</section> </section>
</section> </section>
</section> </section>
<!-- [auth] When adding new errors above, add them to the next section under -->
<!-- [auth] the appropriate operation; the next table for errors to -->
<!-- [auth] operations is automatically generated. -->
<section numbered="true" toc="default"> <section numbered="true" toc="default">
<name>Operations and Their Valid Errors</name> <name>Operations and Their Valid Errors</name>
<t> <t>
This section contains a table that gives the valid error returns This section contains a table that gives the valid error returns
for each protocol operation. The error code NFS4_OK (indicating for each protocol operation. The error code NFS4_OK (indicating
no error) is not listed but should be understood to be returnable no error) is not listed but should be understood to be returnable
by all operations with two important exceptions: by all operations with two important exceptions:
</t> </t>
<ul spacing="normal"> <ul spacing="normal">
skipping to change at line 27344 skipping to change at line 26839
NFS4ERR_SERVERFAULT, NFS4ERR_SERVERFAULT,
NFS4ERR_STALE, NFS4ERR_STALE,
NFS4ERR_SYMLINK, NFS4ERR_SYMLINK,
NFS4ERR_TOO_MANY_OPS, NFS4ERR_TOO_MANY_OPS,
NFS4ERR_WRONG_TYPE NFS4ERR_WRONG_TYPE
</td> </td>
</tr> </tr>
</tbody> </tbody>
</table> </table>
</section> </section>
<!-- [auth] When adding new errors above, add them to the next section under -->
<!-- [auth] the appropriate operation; the next table for errors to -->
<!-- [auth] operations is automatically generated. -->
<section numbered="true" toc="default"> <section numbered="true" toc="default">
<name>Callback Operations and Their Valid Errors</name> <name>Callback Operations and Their Valid Errors</name>
<t> <t>
This section contains a table that gives the valid error returns This section contains a table that gives the valid error returns
for each callback operation. The error code NFS4_OK (indicating for each callback operation. The error code NFS4_OK (indicating
no error) is not listed but should be understood to be returnable no error) is not listed but should be understood to be returnable
by all callback operations with the exception of CB_ILLEGAL. by all callback operations with the exception of CB_ILLEGAL.
</t> </t>
<table anchor="cb_op_error_returns" align="center"> <table anchor="cb_op_error_returns" align="center">
skipping to change at line 27588 skipping to change at line 27080
NFS4ERR_REP_TOO_BIG_TO_CACHE, NFS4ERR_REP_TOO_BIG_TO_CACHE,
NFS4ERR_REQ_TOO_BIG, NFS4ERR_REQ_TOO_BIG,
NFS4ERR_RETRY_UNCACHED_REP, NFS4ERR_RETRY_UNCACHED_REP,
NFS4ERR_SERVERFAULT, NFS4ERR_SERVERFAULT,
NFS4ERR_TOO_MANY_OPS NFS4ERR_TOO_MANY_OPS
</td> </td>
</tr> </tr>
</tbody> </tbody>
</table> </table>
</section> </section>
<!-- [auth] INCLUDE THE AUTO GENERATED ERROR TO OP TABLE -->
<section numbered="true" toc="default"> <section numbered="true" toc="default">
<name>Errors and the Operations That Use Them</name> <name>Errors and the Operations That Use Them</name>
<table anchor="error_op_returns" align="center"> <table anchor="error_op_returns" align="center">
<name>Errors and the Operations That Use Them</name> <name>Errors and the Operations That Use Them</name>
<thead> <thead>
<tr> <tr>
<th align="left">Error</th> <th align="left">Error</th>
<th align="left">Operations</th> <th align="left">Operations</th>
</tr> </tr>
</thead> </thead>
skipping to change at line 29386 skipping to change at line 28877
<td align="left">NFS4ERR_XDEV</td> <td align="left">NFS4ERR_XDEV</td>
<td align="left"> <td align="left">
LINK, LINK,
RENAME RENAME
</td> </td>
</tr> </tr>
</tbody> </tbody>
</table> </table>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- [auth] Copyright (C) The IETF Trust (2007) -->
<!-- [auth] Copyright (C) The Internet Society (2006) -->
<section anchor="nfsv41procedures" numbered="true" toc="default"> <section anchor="nfsv41procedures" numbered="true" toc="default">
<name>NFSv4.1 Procedures</name> <name>NFSv4.1 Procedures</name>
<t> <t>
Both procedures, NULL and COMPOUND, <bcp14>MUST</bcp14> be implemented. Both procedures, NULL and COMPOUND, <bcp14>MUST</bcp14> be implemented.
</t> </t>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- [auth] Copyright (C) The IETF Trust (2007-2008) -->
<!-- [auth] Copyright (C) The Internet Society (2006) -->
<section anchor="PROC_NULL" numbered="true" toc="default"> <section anchor="PROC_NULL" numbered="true" toc="default">
<name>Procedure 0: NULL - No Operation</name> <name>Procedure 0: NULL - No Operation</name>
<section toc="exclude" anchor="PROC_NULL_ARGUMENTS" numbered="true"> <section toc="exclude" anchor="PROC_NULL_ARGUMENTS" numbered="true">
<name>ARGUMENTS</name> <name>ARGUMENTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
void;]]></sourcecode> void;]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="PROC_NULL_RESULTS" numbered="true"> <section toc="exclude" anchor="PROC_NULL_RESULTS" numbered="true">
<name>RESULTS</name> <name>RESULTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
void;]]></sourcecode> void;]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="PROC_NULL_DESCRIPTION" numbered="true"> <section toc="exclude" anchor="PROC_NULL_DESCRIPTION" numbered="true">
<name>DESCRIPTION</name> <name>DESCRIPTION</name>
<t> <t>
This is the standard NULL procedure with the standard void argument and This is the standard NULL procedure with the standard void argument and
void response. void response.
This procedure has no functionality associated with it. Because of This procedure has no functionality associated with it. Because of
this, it is sometimes used to measure the overhead of processing a this, it is sometimes used to measure the overhead of processing a
service request. Therefore, the server <bcp14>SHOULD</bcp14> ensure that no service request. Therefore, the server <bcp14>SHOULD</bcp14> ensure that no
skipping to change at line 29428 skipping to change at line 28913
</t> </t>
</section> </section>
<section toc="exclude" anchor="PROC_NULL_ERRORS" numbered="true"> <section toc="exclude" anchor="PROC_NULL_ERRORS" numbered="true">
<name>ERRORS</name> <name>ERRORS</name>
<t> <t>
None. None.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- [auth] Copyright (C) The IETF Trust (2007-2008) -->
<!-- [auth] Copyright (C) The Internet Society (2006) -->
<section anchor="OP_COMPOUND" numbered="true" toc="default"> <section anchor="OP_COMPOUND" numbered="true" toc="default">
<name>Procedure 1: COMPOUND - Compound Operations</name> <name>Procedure 1: COMPOUND - Compound Operations</name>
<section toc="exclude" anchor="OP_COMPOUND_ARGUMENTS" numbered="true"> <section toc="exclude" anchor="OP_COMPOUND_ARGUMENTS" numbered="true">
<name>ARGUMENTS</name> <name>ARGUMENTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
enum nfs_opnum4 { enum nfs_opnum4 {
OP_ACCESS = 3, OP_ACCESS = 3,
OP_CLOSE = 4, OP_CLOSE = 4,
OP_COMMIT = 5, OP_COMMIT = 5,
OP_CREATE = 6, OP_CREATE = 6,
OP_DELEGPURGE = 7, OP_DELEGPURGE = 7,
OP_DELEGRETURN = 8, OP_DELEGRETURN = 8,
OP_GETATTR = 9, OP_GETATTR = 9,
OP_GETFH = 10, OP_GETFH = 10,
OP_LINK = 11, OP_LINK = 11,
skipping to change at line 29614 skipping to change at line 29096
struct COMPOUND4args { struct COMPOUND4args {
utf8str_cs tag; utf8str_cs tag;
uint32_t minorversion; uint32_t minorversion;
nfs_argop4 argarray<>; nfs_argop4 argarray<>;
}; };
]]></sourcecode> ]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_COMPOUND_RESULTS" numbered="true"> <section toc="exclude" anchor="OP_COMPOUND_RESULTS" numbered="true">
<name>RESULTS</name> <name>RESULTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
union nfs_resop4 switch (nfs_opnum4 resop) { union nfs_resop4 switch (nfs_opnum4 resop) {
case OP_ACCESS: ACCESS4res opaccess; case OP_ACCESS: ACCESS4res opaccess;
case OP_CLOSE: CLOSE4res opclose; case OP_CLOSE: CLOSE4res opclose;
case OP_COMMIT: COMMIT4res opcommit; case OP_COMMIT: COMMIT4res opcommit;
case OP_CREATE: CREATE4res opcreate; case OP_CREATE: CREATE4res opcreate;
case OP_DELEGPURGE: DELEGPURGE4res opdelegpurge; case OP_DELEGPURGE: DELEGPURGE4res opdelegpurge;
case OP_DELEGRETURN: DELEGRETURN4res opdelegreturn; case OP_DELEGRETURN: DELEGRETURN4res opdelegreturn;
case OP_GETATTR: GETATTR4res opgetattr; case OP_GETATTR: GETATTR4res opgetattr;
case OP_GETFH: GETFH4res opgetfh; case OP_GETFH: GETFH4res opgetfh;
case OP_LINK: LINK4res oplink; case OP_LINK: LINK4res oplink;
skipping to change at line 29834 skipping to change at line 29316
the current filehandle as an argument, and many set the current filehandle as an argument, and many set
the current filehandle as part of the results. the current filehandle as part of the results.
The combination of client-specified sequences The combination of client-specified sequences
of operations and current and saved filehandle of operations and current and saved filehandle
arguments and results allows for greater protocol arguments and results allows for greater protocol
flexibility. The best or easiest example of current flexibility. The best or easiest example of current
filehandle usage is a sequence like the following: filehandle usage is a sequence like the following:
</t> </t>
<figure anchor="curfh_example"> <figure anchor="curfh_example">
<sourcecode type=""><![CDATA[ <sourcecode type="nfsv4compound"><![CDATA[
PUTFH fh1 {fh1} PUTFH fh1 {fh1}
LOOKUP "compA" {fh2} LOOKUP "compA" {fh2}
GETATTR {fh2} GETATTR {fh2}
LOOKUP "compB" {fh3} LOOKUP "compB" {fh3}
GETATTR {fh3} GETATTR {fh3}
LOOKUP "compC" {fh4} LOOKUP "compC" {fh4}
GETATTR {fh4} GETATTR {fh4}
GETFH]]></sourcecode> GETFH]]></sourcecode>
</figure> </figure>
<t> <t>
skipping to change at line 29912 skipping to change at line 29394
the current filehandle and the current stateid as a set. the current filehandle and the current stateid as a set.
</t> </t>
<t> <t>
The following example is the common case of a simple READ The following example is the common case of a simple READ
operation with a normal stateid showing that the PUTFH operation with a normal stateid showing that the PUTFH
initializes the current stateid to (0, 0). The subsequent READ initializes the current stateid to (0, 0). The subsequent READ
with stateid (sid1) leaves the current stateid unchanged. with stateid (sid1) leaves the current stateid unchanged.
</t> </t>
<figure anchor="csid_example1"> <figure anchor="csid_example1">
<sourcecode type=""><![CDATA[ <sourcecode type="nfsv4compound"><![CDATA[
PUTFH fh1 - -> {fh1, (0, 0)} PUTFH fh1 - -> {fh1, (0, 0)}
READ (sid1), 0, 1024 {fh1, (0, 0)} -> {fh1, (0, 0)}]]></sourcecode> READ (sid1), 0, 1024 {fh1, (0, 0)} -> {fh1, (0, 0)}]]></sourcecode>
</figure> </figure>
<t> <t>
This next example performs an OPEN with the root This next example performs an OPEN with the root
filehandle and, as a result, generates stateid (sid1). The next filehandle and, as a result, generates stateid (sid1). The next
operation specifies the READ with the argument stateid set such operation specifies the READ with the argument stateid set such
that (seqid, other) are equal to (1, 0), that (seqid, other) are equal to (1, 0),
but the current stateid set by the previous operation is but the current stateid set by the previous operation is
actually used when the operation is evaluated. This allows correct actually used when the operation is evaluated. This allows correct
interaction with any existing, potentially conflicting, interaction with any existing, potentially conflicting,
locks. locks.
</t> </t>
<figure anchor="csid_example2"> <figure anchor="csid_example2">
<sourcecode type=""><![CDATA[ <sourcecode type="nfsv4compound"><![CDATA[
PUTROOTFH - -> {fh1, (0, 0)} PUTROOTFH - -> {fh1, (0, 0)}
OPEN "compA" {fh1, (0, 0)} -> {fh2, (sid1)} OPEN "compA" {fh1, (0, 0)} -> {fh2, (sid1)}
READ (1, 0), 0, 1024 {fh2, (sid1)} -> {fh2, (sid1)} READ (1, 0), 0, 1024 {fh2, (sid1)} -> {fh2, (sid1)}
CLOSE (1, 0) {fh2, (sid1)} -> {fh2, (sid2)}]]></sourcecode> CLOSE (1, 0) {fh2, (sid1)} -> {fh2, (sid2)}]]></sourcecode>
</figure> </figure>
<t> <t>
This next example is similar to the second in how This next example is similar to the second in how
it passes the stateid sid2 generated by the LOCK it passes the stateid sid2 generated by the LOCK
operation to the next READ operation. This allows operation to the next READ operation. This allows
the client to explicitly surround a single I/O the client to explicitly surround a single I/O
operation with a lock and its appropriate stateid to operation with a lock and its appropriate stateid to
guarantee correctness with other client locks. The guarantee correctness with other client locks. The
example also shows how SAVEFH and RESTOREFH can example also shows how SAVEFH and RESTOREFH can
save and later reuse a filehandle and stateid, passing them as the save and later reuse a filehandle and stateid, passing them as the
current filehandle and stateid to a READ operation. current filehandle and stateid to a READ operation.
</t> </t>
<figure anchor="csid_example3"> <figure anchor="csid_example3">
<sourcecode type=""><![CDATA[ <sourcecode type="nfsv4compound"><![CDATA[
PUTFH fh1 - -> {fh1, (0, 0)} PUTFH fh1 - -> {fh1, (0, 0)}
LOCK 0, 1024, (sid1) {fh1, (sid1)} -> {fh1, (sid2)} LOCK 0, 1024, (sid1) {fh1, (sid1)} -> {fh1, (sid2)}
READ (1, 0), 0, 1024 {fh1, (sid2)} -> {fh1, (sid2)} READ (1, 0), 0, 1024 {fh1, (sid2)} -> {fh1, (sid2)}
LOCKU 0, 1024, (1, 0) {fh1, (sid2)} -> {fh1, (sid3)} LOCKU 0, 1024, (1, 0) {fh1, (sid2)} -> {fh1, (sid3)}
SAVEFH {fh1, (sid3)} -> {fh1, (sid3)} SAVEFH {fh1, (sid3)} -> {fh1, (sid3)}
PUTFH fh2 {fh1, (sid3)} -> {fh2, (0, 0)} PUTFH fh2 {fh1, (sid3)} -> {fh2, (0, 0)}
WRITE (1, 0), 0, 1024 {fh2, (0, 0)} -> {fh2, (0, 0)} WRITE (1, 0), 0, 1024 {fh2, (0, 0)} -> {fh2, (0, 0)}
RESTOREFH {fh2, (0, 0)} -> {fh1, (sid3)} RESTOREFH {fh2, (0, 0)} -> {fh1, (sid3)}
skipping to change at line 29968 skipping to change at line 29450
</figure> </figure>
<t> <t>
The final example shows a disallowed use of The final example shows a disallowed use of
the current stateid. The client is attempting the current stateid. The client is attempting
to implicitly pass an anonymous special stateid, (0,0), to to implicitly pass an anonymous special stateid, (0,0), to
the READ operation. The server <bcp14>MUST</bcp14> return NFS4ERR_BAD_STATEID the READ operation. The server <bcp14>MUST</bcp14> return NFS4ERR_BAD_STATEID
in the reply to the READ operation. in the reply to the READ operation.
</t> </t>
<figure anchor="csid_example4"> <figure anchor="csid_example4">
<sourcecode type=""><![CDATA[ <sourcecode type="nfsv4compound"><![CDATA[
PUTFH fh1 - -> {fh1, (0, 0)} PUTFH fh1 - -> {fh1, (0, 0)}
READ (1, 0), 0, 1024 {fh1, (0, 0)} -> NFS4ERR_BAD_STATEID]]></sourcecode> READ (1, 0), 0, 1024 {fh1, (0, 0)} -> NFS4ERR_BAD_STATEID]]></sourcecode>
</figure> </figure>
</section> </section>
</section> </section>
</section> </section>
<section toc="exclude" anchor="OP_COMPOUND_ERRORS" numbered="true"> <section toc="exclude" anchor="OP_COMPOUND_ERRORS" numbered="true">
<name>ERRORS</name> <name>ERRORS</name>
<t> <t>
COMPOUND will of course return every error that each operation on COMPOUND will of course return every error that each operation on
skipping to change at line 30039 skipping to change at line 29521
<td align="left"> </td> <td align="left"> </td>
</tr> </tr>
<tr> <tr>
<td align="left">NFS4ERR_REQ_TOO_BIG</td> <td align="left">NFS4ERR_REQ_TOO_BIG</td>
<td align="left"> </td> <td align="left"> </td>
</tr> </tr>
</tbody> </tbody>
</table> </table>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- [auth] Copyright (C) The IETF Trust (2007) -->
<!-- [auth] Copyright (C) The Internet Society (2006) -->
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- [auth] Copyright (C) The IETF Trust (2007-2008) -->
<section anchor="operation_mandlist" numbered="true" toc="default"> <section anchor="operation_mandlist" numbered="true" toc="default">
<name>Operations: <bcp14>REQUIRED</bcp14>, <bcp14>RECOMMENDED</bcp14>, or <bcp14>OPTIONAL</bcp14></name> <name>Operations: <bcp14>REQUIRED</bcp14>, <bcp14>RECOMMENDED</bcp14>, or <bcp14>OPTIONAL</bcp14></name>
<t> <t>
The following tables summarize the operations of the NFSv4.1 The following tables summarize the operations of the NFSv4.1
protocol and the corresponding designation of <bcp14>REQUIRED</bcp14>, protocol and the corresponding designation of <bcp14>REQUIRED</bcp14>,
<bcp14>RECOMMENDED</bcp14>, and <bcp14>OPTIONAL</bcp14> to implement or <bcp14>MUST NOT</bcp14> implement. The <bcp14>RECOMMENDED</bcp14>, and <bcp14>OPTIONAL</bcp14> to implement or <bcp14>MUST NOT</bcp14> implement. The
designation of <bcp14>MUST NOT</bcp14> implement is reserved for those operations designation of <bcp14>MUST NOT</bcp14> implement is reserved for those operations
that were defined in NFSv4.0 and <bcp14>MUST NOT</bcp14> be implemented in NFSv4.1. that were defined in NFSv4.0 and <bcp14>MUST NOT</bcp14> be implemented in NFSv4.1.
</t> </t>
<t> <t>
skipping to change at line 30629 skipping to change at line 30106
<tr> <tr>
<td align="left"> CB_WANTS_CANCELLED </td> <td align="left"> CB_WANTS_CANCELLED </td>
<td align="left">OPT</td> <td align="left">OPT</td>
<td align="left">FDELG, DDELG, pNFS (REQ)</td> <td align="left">FDELG, DDELG, pNFS (REQ)</td>
<td align="left"> <td align="left">
<xref target="OP_CB_WANTS_CANCELLED" format="default"/> </td> <xref target="OP_CB_WANTS_CANCELLED" format="default"/> </td>
</tr> </tr>
</tbody> </tbody>
</table> </table>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- [auth] Copyright (C) The IETF Trust (2007) -->
<!-- [auth] Copyright (C) The Internet Society (2006) -->
<section anchor="nfsv41operations" numbered="true" toc="default"> <section anchor="nfsv41operations" numbered="true" toc="default">
<name>NFSv4.1 Operations</name> <name>NFSv4.1 Operations</name>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- [auth] Copyright (C) The IETF Trust (2007) -->
<!-- [auth] Copyright (C) The Internet Society (2006) -->
<section anchor="OP_ACCESS" numbered="true" toc="default"> <section anchor="OP_ACCESS" numbered="true" toc="default">
<name>Operation 3: ACCESS - Check Access Rights</name> <name>Operation 3: ACCESS - Check Access Rights</name>
<section toc="exclude" anchor="OP_ACCESS_ARGUMENTS" numbered="true"> <section toc="exclude" anchor="OP_ACCESS_ARGUMENTS" numbered="true">
<name>ARGUMENTS</name> <name>ARGUMENTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
const ACCESS4_READ = 0x00000001; const ACCESS4_READ = 0x00000001;
const ACCESS4_LOOKUP = 0x00000002; const ACCESS4_LOOKUP = 0x00000002;
const ACCESS4_MODIFY = 0x00000004; const ACCESS4_MODIFY = 0x00000004;
const ACCESS4_EXTEND = 0x00000008; const ACCESS4_EXTEND = 0x00000008;
const ACCESS4_DELETE = 0x00000010; const ACCESS4_DELETE = 0x00000010;
const ACCESS4_EXECUTE = 0x00000020; const ACCESS4_EXECUTE = 0x00000020;
struct ACCESS4args { struct ACCESS4args {
/* CURRENT_FH: object */ /* CURRENT_FH: object */
uint32_t access; uint32_t access;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_ACCESS_RESULTS" numbered="true"> <section toc="exclude" anchor="OP_ACCESS_RESULTS" numbered="true">
<name>RESULTS</name> <name>RESULTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct ACCESS4resok { struct ACCESS4resok {
uint32_t supported; uint32_t supported;
uint32_t access; uint32_t access;
}; };
union ACCESS4res switch (nfsstat4 status) { union ACCESS4res switch (nfsstat4 status) {
case NFS4_OK: case NFS4_OK:
ACCESS4resok resok4; ACCESS4resok resok4;
default: default:
void; void;
skipping to change at line 30982 skipping to change at line 30453
permissions on the directory in which the file resides, instead of permissions on the directory in which the file resides, instead of
being determined by the permissions of the file itself. Therefore, being determined by the permissions of the file itself. Therefore,
the mask returned enumerating which access rights can be determined the mask returned enumerating which access rights can be determined
will have the ACCESS4_DELETE value set to 0. This indicates to the will have the ACCESS4_DELETE value set to 0. This indicates to the
client that the server was unable to check that particular access client that the server was unable to check that particular access
right. The ACCESS4_DELETE bit in the access mask returned will then be right. The ACCESS4_DELETE bit in the access mask returned will then be
ignored by the client. ignored by the client.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- [auth] Copyright (C) The IETF Trust (2007) -->
<!-- [auth] Copyright (C) The Internet Society (2006) -->
<section anchor="OP_CLOSE" numbered="true" toc="default"> <section anchor="OP_CLOSE" numbered="true" toc="default">
<name>Operation 4: CLOSE - Close File</name> <name>Operation 4: CLOSE - Close File</name>
<section toc="exclude" anchor="OP_CLOSE_ARGUMENTS" numbered="true"> <section toc="exclude" anchor="OP_CLOSE_ARGUMENTS" numbered="true">
<name>ARGUMENTS</name> <name>ARGUMENTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct CLOSE4args { struct CLOSE4args {
/* CURRENT_FH: object */ /* CURRENT_FH: object */
seqid4 seqid; seqid4 seqid;
stateid4 open_stateid; stateid4 open_stateid;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_CLOSE_RESULTS" numbered="true"> <section toc="exclude" anchor="OP_CLOSE_RESULTS" numbered="true">
<name>RESULTS</name> <name>RESULTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
union CLOSE4res switch (nfsstat4 status) { union CLOSE4res switch (nfsstat4 status) {
case NFS4_OK: case NFS4_OK:
stateid4 open_stateid; stateid4 open_stateid;
default: default:
void; void;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_CLOSE_DESCRIPTION" numbered="true"> <section toc="exclude" anchor="OP_CLOSE_DESCRIPTION" numbered="true">
<name>DESCRIPTION</name> <name>DESCRIPTION</name>
<t> <t>
skipping to change at line 31064 skipping to change at line 30532
where they were not previously. Servers may choose to respond where they were not previously. Servers may choose to respond
immediately if there are pending delegation want requests or may immediately if there are pending delegation want requests or may
respond to the situation at a later time. respond to the situation at a later time.
</t> </t>
</section> </section>
</section> </section>
<section anchor="OP_COMMIT" numbered="true" toc="default"> <section anchor="OP_COMMIT" numbered="true" toc="default">
<name>Operation 5: COMMIT - Commit Cached Data</name> <name>Operation 5: COMMIT - Commit Cached Data</name>
<section toc="exclude" anchor="OP_COMMIT_ARGUMENTS" numbered="true"> <section toc="exclude" anchor="OP_COMMIT_ARGUMENTS" numbered="true">
<name>ARGUMENTS</name> <name>ARGUMENTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct COMMIT4args { struct COMMIT4args {
/* CURRENT_FH: file */ /* CURRENT_FH: file */
offset4 offset; offset4 offset;
count4 count; count4 count;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_COMMIT_RESULTS" numbered="true"> <section toc="exclude" anchor="OP_COMMIT_RESULTS" numbered="true">
<name>RESULTS</name> <name>RESULTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct COMMIT4resok { struct COMMIT4resok {
verifier4 writeverf; verifier4 writeverf;
}; };
union COMMIT4res switch (nfsstat4 status) { union COMMIT4res switch (nfsstat4 status) {
case NFS4_OK: case NFS4_OK:
COMMIT4resok resok4; COMMIT4resok resok4;
default: default:
void; void;
};]]></sourcecode> };]]></sourcecode>
skipping to change at line 31199 skipping to change at line 30667
by WRITE, the only way to ensure progress is to retransmit all by WRITE, the only way to ensure progress is to retransmit all
of the buffers with WRITE requests with the FILE_SYNC4 stable parameter. of the buffers with WRITE requests with the FILE_SYNC4 stable parameter.
</t> </t>
<t> <t>
The above description applies to page-cache-based systems as well as The above description applies to page-cache-based systems as well as
buffer-cache-based systems. In the former systems, the virtual memory buffer-cache-based systems. In the former systems, the virtual memory
system will need to be modified instead of the buffer cache. system will need to be modified instead of the buffer cache.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- [auth] Copyright (C) The IETF Trust (2007-2008) -->
<!-- [auth] Copyright (C) The Internet Society (2006) -->
<section anchor="OP_CREATE" numbered="true" toc="default"> <section anchor="OP_CREATE" numbered="true" toc="default">
<name>Operation 6: CREATE - Create a Non-Regular File Object</name> <name>Operation 6: CREATE - Create a Non-Regular File Object</name>
<section toc="exclude" anchor="OP_CREATE_ARGUMENTS" numbered="true"> <section toc="exclude" anchor="OP_CREATE_ARGUMENTS" numbered="true">
<name>ARGUMENTS</name> <name>ARGUMENTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
union createtype4 switch (nfs_ftype4 type) { union createtype4 switch (nfs_ftype4 type) {
case NF4LNK: case NF4LNK:
linktext4 linkdata; linktext4 linkdata;
case NF4BLK: case NF4BLK:
case NF4CHR: case NF4CHR:
specdata4 devdata; specdata4 devdata;
case NF4SOCK: case NF4SOCK:
case NF4FIFO: case NF4FIFO:
case NF4DIR: case NF4DIR:
void; void;
skipping to change at line 31230 skipping to change at line 30695
struct CREATE4args { struct CREATE4args {
/* CURRENT_FH: directory for creation */ /* CURRENT_FH: directory for creation */
createtype4 objtype; createtype4 objtype;
component4 objname; component4 objname;
fattr4 createattrs; fattr4 createattrs;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_CREATE_RESULTS" numbered="true"> <section toc="exclude" anchor="OP_CREATE_RESULTS" numbered="true">
<name>RESULTS</name> <name>RESULTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct CREATE4resok { struct CREATE4resok {
change_info4 cinfo; change_info4 cinfo;
bitmap4 attrset; /* attributes set */ bitmap4 attrset; /* attributes set */
}; };
union CREATE4res switch (nfsstat4 status) { union CREATE4res switch (nfsstat4 status) {
case NFS4_OK: case NFS4_OK:
/* new CURRENTFH: created object */ /* new CURRENTFH: created object */
CREATE4resok resok4; CREATE4resok resok4;
default: default:
skipping to change at line 31350 skipping to change at line 30815
</section> </section>
<section toc="exclude" anchor="OP_CREATE_IMPLEMENTATION" numbered="true"> <section toc="exclude" anchor="OP_CREATE_IMPLEMENTATION" numbered="true">
<name>IMPLEMENTATION</name> <name>IMPLEMENTATION</name>
<t> <t>
If the client desires to set attribute values after the create, a If the client desires to set attribute values after the create, a
SETATTR operation can be added to the COMPOUND request so that the SETATTR operation can be added to the COMPOUND request so that the
appropriate attributes will be set. appropriate attributes will be set.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- [auth] Copyright (C) The IETF Trust (2007) -->
<!-- [auth] Copyright (C) The Internet Society (2006) -->
<section anchor="OP_DELEGPURGE" numbered="true" toc="default"> <section anchor="OP_DELEGPURGE" numbered="true" toc="default">
<name>Operation 7: DELEGPURGE - Purge Delegations Awaiting Recovery</name> <name>Operation 7: DELEGPURGE - Purge Delegations Awaiting Recovery</name>
<section toc="exclude" anchor="OP_DELEGPURGE_ARGUMENTS" numbered="true"> <section toc="exclude" anchor="OP_DELEGPURGE_ARGUMENTS" numbered="true">
<name>ARGUMENTS</name> <name>ARGUMENTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct DELEGPURGE4args { struct DELEGPURGE4args {
clientid4 clientid; clientid4 clientid;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_DELEGPURGE_RESULTS" numbered="true"> <section toc="exclude" anchor="OP_DELEGPURGE_RESULTS" numbered="true">
<name>RESULTS</name> <name>RESULTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct DELEGPURGE4res { struct DELEGPURGE4res {
nfsstat4 status; nfsstat4 status;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_DELEGPURGE_DESCRIPTION" numbered="true"> <section toc="exclude" anchor="OP_DELEGPURGE_DESCRIPTION" numbered="true">
<name>DESCRIPTION</name> <name>DESCRIPTION</name>
<t> <t>
This operation purges all of the delegations awaiting recovery for a given client. This operation purges all of the delegations awaiting recovery for a given client.
This is useful for clients that do not commit delegation information This is useful for clients that do not commit delegation information
to stable storage to indicate that conflicting requests need not be to stable storage to indicate that conflicting requests need not be
skipping to change at line 31408 skipping to change at line 30870
resulted in a delegation, the client might experience a failure resulted in a delegation, the client might experience a failure
before it both received the delegation and before it both received the delegation and
committed the delegation to the client's stable storage. committed the delegation to the client's stable storage.
</t> </t>
<t> <t>
The server <bcp14>MAY</bcp14> support DELEGPURGE, but if it does not, it <bcp14>MUST NOT</bcp14> The server <bcp14>MAY</bcp14> support DELEGPURGE, but if it does not, it <bcp14>MUST NOT</bcp14>
support CLAIM_DELEGATE_PREV and <bcp14>MUST NOT</bcp14> support CLAIM_DELEG_PREV_FH. support CLAIM_DELEGATE_PREV and <bcp14>MUST NOT</bcp14> support CLAIM_DELEG_PREV_FH.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- [auth] Copyright (C) The IETF Trust (2007) -->
<!-- [auth] Copyright (C) The Internet Society (2006) -->
<section anchor="OP_DELEGRETURN" numbered="true" toc="default"> <section anchor="OP_DELEGRETURN" numbered="true" toc="default">
<name>Operation 8: DELEGRETURN - Return Delegation</name> <name>Operation 8: DELEGRETURN - Return Delegation</name>
<section toc="exclude" anchor="OP_DELEGRETURN_ARGUMENTS" numbered="true"> <section toc="exclude" anchor="OP_DELEGRETURN_ARGUMENTS" numbered="true">
<name>ARGUMENTS</name> <name>ARGUMENTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct DELEGRETURN4args { struct DELEGRETURN4args {
/* CURRENT_FH: delegated object */ /* CURRENT_FH: delegated object */
stateid4 deleg_stateid; stateid4 deleg_stateid;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_DELEGRETURN_RESULTS" numbered="true"> <section toc="exclude" anchor="OP_DELEGRETURN_RESULTS" numbered="true">
<name>RESULTS</name> <name>RESULTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct DELEGRETURN4res { struct DELEGRETURN4res {
nfsstat4 status; nfsstat4 status;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_DELEGRETURN_DESCRIPTION" numbered="true"> <section toc="exclude" anchor="OP_DELEGRETURN_DESCRIPTION" numbered="true">
<name>DESCRIPTION</name> <name>DESCRIPTION</name>
<t> <t>
The DELEGRETURN operation returns the delegation represented by The DELEGRETURN operation returns the delegation represented by
the current filehandle and stateid. the current filehandle and stateid.
</t> </t>
skipping to change at line 31452 skipping to change at line 30911
flavor, and if applicable, the GSS mechanism, combination flavor, and if applicable, the GSS mechanism, combination
that acquired the delegation also be the one to send that acquired the delegation also be the one to send
DELEGRETURN on the file. This might not be possible DELEGRETURN on the file. This might not be possible
if credentials for the principal are no longer if credentials for the principal are no longer
available. The server <bcp14>MAY</bcp14> allow the machine credential available. The server <bcp14>MAY</bcp14> allow the machine credential
or SSV credential (see <xref target="OP_EXCHANGE_ID" format="default"/>) to send DELEGRETURN. or SSV credential (see <xref target="OP_EXCHANGE_ID" format="default"/>) to send DELEGRETURN.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- [auth] Copyright (C) The IETF Trust (2007-2008) -->
<!-- [auth] Copyright (C) The Internet Society (2006) -->
<section anchor="OP_GETATTR" numbered="true" toc="default"> <section anchor="OP_GETATTR" numbered="true" toc="default">
<name>Operation 9: GETATTR - Get Attributes</name> <name>Operation 9: GETATTR - Get Attributes</name>
<section toc="exclude" anchor="OP_GETATTR_ARGUMENTS" numbered="true"> <section toc="exclude" anchor="OP_GETATTR_ARGUMENTS" numbered="true">
<name>ARGUMENTS</name> <name>ARGUMENTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct GETATTR4args { struct GETATTR4args {
/* CURRENT_FH: object */ /* CURRENT_FH: object */
bitmap4 attr_request; bitmap4 attr_request;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_GETATTR_RESULTS" numbered="true"> <section toc="exclude" anchor="OP_GETATTR_RESULTS" numbered="true">
<name>RESULTS</name> <name>RESULTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct GETATTR4resok { struct GETATTR4resok {
fattr4 obj_attributes; fattr4 obj_attributes;
}; };
union GETATTR4res switch (nfsstat4 status) { union GETATTR4res switch (nfsstat4 status) {
case NFS4_OK: case NFS4_OK:
GETATTR4resok resok4; GETATTR4resok resok4;
default: default:
void; void;
};]]></sourcecode> };]]></sourcecode>
skipping to change at line 31551 skipping to change at line 31007
</li> </li>
</ul> </ul>
<t> <t>
Unless one of the above happens very quickly, Unless one of the above happens very quickly,
one or more NFS4ERR_DELAY errors will be returned one or more NFS4ERR_DELAY errors will be returned
while a delegation is outstanding. while a delegation is outstanding.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- [auth] Copyright (C) The IETF Trust (2007-2008) -->
<!-- [auth] Copyright (C) The Internet Society (2006) -->
<section anchor="OP_GETFH" numbered="true" toc="default"> <section anchor="OP_GETFH" numbered="true" toc="default">
<name>Operation 10: GETFH - Get Current Filehandle</name> <name>Operation 10: GETFH - Get Current Filehandle</name>
<section toc="exclude" anchor="OP_GETFH_ARGUMENTS" numbered="true"> <section toc="exclude" anchor="OP_GETFH_ARGUMENTS" numbered="true">
<name>ARGUMENTS</name> <name>ARGUMENTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
/* CURRENT_FH: */ /* CURRENT_FH: */
void; void;
]]></sourcecode> ]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_GETFH_RESULTS" numbered="true"> <section toc="exclude" anchor="OP_GETFH_RESULTS" numbered="true">
<name>RESULTS</name> <name>RESULTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct GETFH4resok { struct GETFH4resok {
nfs_fh4 object; nfs_fh4 object;
}; };
union GETFH4res switch (nfsstat4 status) { union GETFH4res switch (nfsstat4 status) {
case NFS4_OK: case NFS4_OK:
GETFH4resok resok4; GETFH4resok resok4;
default: default:
void; void;
};]]></sourcecode> };]]></sourcecode>
skipping to change at line 31618 skipping to change at line 31071
</li> </li>
<li> <li>
LOOKUP (entry name) LOOKUP (entry name)
</li> </li>
<li> <li>
GETFH GETFH
</li> </li>
</ul> </ul>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- [auth] Copyright (C) The IETF Trust (2007) -->
<!-- [auth] Copyright (C) The Internet Society (2006) -->
<section anchor="OP_LINK" numbered="true" toc="default"> <section anchor="OP_LINK" numbered="true" toc="default">
<name>Operation 11: LINK - Create Link to a File</name> <name>Operation 11: LINK - Create Link to a File</name>
<section toc="exclude" anchor="OP_LINK_ARGUMENTS" numbered="true"> <section toc="exclude" anchor="OP_LINK_ARGUMENTS" numbered="true">
<name>ARGUMENTS</name> <name>ARGUMENTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct LINK4args { struct LINK4args {
/* SAVED_FH: source object */ /* SAVED_FH: source object */
/* CURRENT_FH: target directory */ /* CURRENT_FH: target directory */
component4 newname; component4 newname;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_LINK_RESULTS" numbered="true"> <section toc="exclude" anchor="OP_LINK_RESULTS" numbered="true">
<name>RESULTS</name> <name>RESULTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct LINK4resok { struct LINK4resok {
change_info4 cinfo; change_info4 cinfo;
}; };
union LINK4res switch (nfsstat4 status) { union LINK4res switch (nfsstat4 status) {
case NFS4_OK: case NFS4_OK:
LINK4resok resok4; LINK4resok resok4;
default: default:
void; void;
};]]></sourcecode> };]]></sourcecode>
skipping to change at line 31761 skipping to change at line 31211
</t> </t>
<t> <t>
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.
</t> </t>
<t> <t>
Note that symbolic links are created with the CREATE operation. Note that symbolic links are created with the CREATE operation.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- [auth] Copyright (C) The IETF Trust (2007-2008) -->
<!-- [auth] Copyright (C) The Internet Society (2006) -->
<section anchor="OP_LOCK" numbered="true" toc="default"> <section anchor="OP_LOCK" numbered="true" toc="default">
<name>Operation 12: LOCK - Create Lock</name> <name>Operation 12: LOCK - Create Lock</name>
<section toc="exclude" anchor="OP_LOCK_ARGUMENTS" numbered="true"> <section toc="exclude" anchor="OP_LOCK_ARGUMENTS" numbered="true">
<name>ARGUMENTS</name> <name>ARGUMENTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
/* /*
* For LOCK, transition from open_stateid and lock_owner * For LOCK, transition from open_stateid and lock_owner
* to a lock stateid. * to a lock stateid.
*/ */
struct open_to_lock_owner4 { struct open_to_lock_owner4 {
seqid4 open_seqid; seqid4 open_seqid;
stateid4 open_stateid; stateid4 open_stateid;
seqid4 lock_seqid; seqid4 lock_seqid;
lock_owner4 lock_owner; lock_owner4 lock_owner;
}; };
skipping to change at line 31810 skipping to change at line 31257
/* CURRENT_FH: file */ /* CURRENT_FH: file */
nfs_lock_type4 locktype; nfs_lock_type4 locktype;
bool reclaim; bool reclaim;
offset4 offset; offset4 offset;
length4 length; length4 length;
locker4 locker; locker4 locker;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_LOCK_RESULTS" numbered="true"> <section toc="exclude" anchor="OP_LOCK_RESULTS" numbered="true">
<name>RESULTS</name> <name>RESULTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct LOCK4denied { struct LOCK4denied {
offset4 offset; offset4 offset;
length4 length; length4 length;
nfs_lock_type4 locktype; nfs_lock_type4 locktype;
lock_owner4 owner; lock_owner4 owner;
}; };
struct LOCK4resok { struct LOCK4resok {
stateid4 lock_stateid; stateid4 lock_stateid;
}; };
skipping to change at line 31996 skipping to change at line 31443
When one or more clients hold OPEN_DELEGATE_READ delegations, any LOCK operation When one or more clients hold OPEN_DELEGATE_READ delegations, any LOCK operation
where the server is implementing mandatory locking semantics <bcp14>MUST</bcp14> where the server is implementing mandatory locking semantics <bcp14>MUST</bcp14>
result in the recall of all such delegations. The LOCK operation may result in the recall of all such delegations. The LOCK operation may
not be granted until all such delegations are returned or revoked. not be granted until all such delegations are returned or revoked.
Except where this Except where this
happens very quickly, one or more NFS4ERR_DELAY errors will be happens very quickly, one or more NFS4ERR_DELAY errors will be
returned to requests made while the delegation remains outstanding. returned to requests made while the delegation remains outstanding.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- [auth] Copyright (C) The IETF Trust (2007-2008) -->
<!-- [auth] Copyright (C) The Internet Society (2006) -->
<section anchor="OP_LOCKT" numbered="true" toc="default"> <section anchor="OP_LOCKT" numbered="true" toc="default">
<name>Operation 13: LOCKT - Test for Lock</name> <name>Operation 13: LOCKT - Test for Lock</name>
<section toc="exclude" anchor="OP_LOCKT_ARGUMENTS" numbered="true"> <section toc="exclude" anchor="OP_LOCKT_ARGUMENTS" numbered="true">
<name>ARGUMENTS</name> <name>ARGUMENTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct LOCKT4args { struct LOCKT4args {
/* CURRENT_FH: file */ /* CURRENT_FH: file */
nfs_lock_type4 locktype; nfs_lock_type4 locktype;
offset4 offset; offset4 offset;
length4 length; length4 length;
lock_owner4 owner; lock_owner4 owner;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_LOCKT_RESULTS" numbered="true"> <section toc="exclude" anchor="OP_LOCKT_RESULTS" numbered="true">
<name>RESULTS</name> <name>RESULTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
union LOCKT4res switch (nfsstat4 status) { union LOCKT4res switch (nfsstat4 status) {
case NFS4ERR_DENIED: case NFS4ERR_DENIED:
LOCK4denied denied; LOCK4denied denied;
case NFS4_OK: case NFS4_OK:
void; void;
default: default:
void; void;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_LOCKT_DESCRIPTION" numbered="true"> <section toc="exclude" anchor="OP_LOCKT_DESCRIPTION" numbered="true">
skipping to change at line 32100 skipping to change at line 31544
same range and lock-owner would fail with NFS4ERR_LOCK_RANGE. same range and lock-owner would fail with NFS4ERR_LOCK_RANGE.
</t> </t>
<t> <t>
When a client holds an OPEN_DELEGATE_WRITE delegation, it may choose When a client holds an OPEN_DELEGATE_WRITE delegation, it may choose
(see <xref target="OP_LOCK_IMPLEMENTATION" format="default"/>) to handle LOCK (see <xref target="OP_LOCK_IMPLEMENTATION" format="default"/>) to handle LOCK
requests locally. In such a case, LOCKT requests will similarly requests locally. In such a case, LOCKT requests will similarly
be handled locally. be handled locally.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- [auth] Copyright (C) The IETF Trust (2007-2008) -->
<!-- [auth] Copyright (C) The Internet Society (2006) -->
<section anchor="OP_LOCKU" numbered="true" toc="default"> <section anchor="OP_LOCKU" numbered="true" toc="default">
<name>Operation 14: LOCKU - Unlock File</name> <name>Operation 14: LOCKU - Unlock File</name>
<section toc="exclude" anchor="OP_LOCKU_ARGUMENTS" numbered="true"> <section toc="exclude" anchor="OP_LOCKU_ARGUMENTS" numbered="true">
<name>ARGUMENTS</name> <name>ARGUMENTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct LOCKU4args { struct LOCKU4args {
/* CURRENT_FH: file */ /* CURRENT_FH: file */
nfs_lock_type4 locktype; nfs_lock_type4 locktype;
seqid4 seqid; seqid4 seqid;
stateid4 lock_stateid; stateid4 lock_stateid;
offset4 offset; offset4 offset;
length4 length; length4 length;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_LOCKU_RESULTS" numbered="true"> <section toc="exclude" anchor="OP_LOCKU_RESULTS" numbered="true">
<name>RESULTS</name> <name>RESULTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
union LOCKU4res switch (nfsstat4 status) { union LOCKU4res switch (nfsstat4 status) {
case NFS4_OK: case NFS4_OK:
stateid4 lock_stateid; stateid4 lock_stateid;
default: default:
void; void;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_LOCKU_DESCRIPTION" numbered="true"> <section toc="exclude" anchor="OP_LOCKU_DESCRIPTION" numbered="true">
<name>DESCRIPTION</name> <name>DESCRIPTION</name>
<t> <t>
skipping to change at line 32189 skipping to change at line 31630
unlocked. unlocked.
</t> </t>
<t> <t>
When a client holds an OPEN_DELEGATE_WRITE delegation, it may choose When a client holds an OPEN_DELEGATE_WRITE delegation, it may choose
(see <xref target="OP_LOCK_IMPLEMENTATION" format="default"/>) to handle LOCK (see <xref target="OP_LOCK_IMPLEMENTATION" format="default"/>) to handle LOCK
requests locally. In such a case, LOCKU operations will similarly requests locally. In such a case, LOCKU operations will similarly
be handled locally. be handled locally.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- [auth] Copyright (C) The IETF Trust (2007) -->
<!-- [auth] Copyright (C) The Internet Society (2006) -->
<section anchor="OP_LOOKUP" numbered="true" toc="default"> <section anchor="OP_LOOKUP" numbered="true" toc="default">
<name>Operation 15: LOOKUP - Lookup Filename</name> <name>Operation 15: LOOKUP - Lookup Filename</name>
<section toc="exclude" anchor="OP_LOOKUP_ARGUMENTS" numbered="true"> <section toc="exclude" anchor="OP_LOOKUP_ARGUMENTS" numbered="true">
<name>ARGUMENTS</name> <name>ARGUMENTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct LOOKUP4args { struct LOOKUP4args {
/* CURRENT_FH: directory */ /* CURRENT_FH: directory */
component4 objname; component4 objname;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_LOOKUP_RESULTS" numbered="true"> <section toc="exclude" anchor="OP_LOOKUP_RESULTS" numbered="true">
<name>RESULTS</name> <name>RESULTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct LOOKUP4res { struct LOOKUP4res {
/* New CURRENT_FH: object */ /* New CURRENT_FH: object */
nfsstat4 status; nfsstat4 status;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_LOOKUP_DESCRIPTION" numbered="true"> <section toc="exclude" anchor="OP_LOOKUP_DESCRIPTION" numbered="true">
<name>DESCRIPTION</name> <name>DESCRIPTION</name>
<t> <t>
The LOOKUP operation looks up or finds a file system object using the The LOOKUP operation looks up or finds a file system object using the
directory specified by the current filehandle. LOOKUP evaluates the directory specified by the current filehandle. LOOKUP evaluates the
skipping to change at line 32236 skipping to change at line 31674
obey the UTF-8 definition, the error NFS4ERR_INVAL will be returned. obey the UTF-8 definition, the error NFS4ERR_INVAL will be returned.
</t> </t>
</section> </section>
<section toc="exclude" anchor="OP_LOOKUP_IMPLEMENTATION" numbered="true"> <section toc="exclude" anchor="OP_LOOKUP_IMPLEMENTATION" numbered="true">
<name>IMPLEMENTATION</name> <name>IMPLEMENTATION</name>
<t> <t>
If the client wants to achieve the effect of a multi-component look up, If the client wants to achieve the effect of a multi-component look up,
it may construct a COMPOUND request such as (and obtain each it may construct a COMPOUND request such as (and obtain each
filehandle): filehandle):
</t> </t>
<sourcecode type=""><![CDATA[ <sourcecode type="nfsv4compound"><![CDATA[
PUTFH (directory filehandle) PUTFH (directory filehandle)
LOOKUP "pub" LOOKUP "pub"
GETFH GETFH
LOOKUP "foo" LOOKUP "foo"
GETFH GETFH
LOOKUP "bar" LOOKUP "bar"
GETFH]]></sourcecode> GETFH]]></sourcecode>
<t> <t>
Unlike NFSv3, NFSv4.1 allows LOOKUP requests to cross mountpoints on the Unlike NFSv3, NFSv4.1 allows LOOKUP requests to cross mountpoints on the
server. The client can detect a mountpoint crossing by comparing the server. The client can detect a mountpoint crossing by comparing the
skipping to change at line 32279 skipping to change at line 31717
is responsible for all parsing of filenames including filenames that is responsible for all parsing of filenames including filenames that
are modified by symbolic links encountered during the look up process. are modified by symbolic links encountered during the look up process.
</t> </t>
<t> <t>
If the current filehandle supplied is not a directory but a symbolic If the current filehandle supplied is not a directory but a symbolic
link, the error NFS4ERR_SYMLINK is returned as the error. For all link, the error NFS4ERR_SYMLINK is returned as the error. For all
other non-directory file types, the error NFS4ERR_NOTDIR is returned. other non-directory file types, the error NFS4ERR_NOTDIR is returned.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- [auth] Copyright (C) The IETF Trust (2007-2008) -->
<!-- [auth] Copyright (C) The Internet Society (2006) -->
<section anchor="OP_LOOKUPP" numbered="true" toc="default"> <section anchor="OP_LOOKUPP" numbered="true" toc="default">
<name>Operation 16: LOOKUPP - Lookup Parent Directory</name> <name>Operation 16: LOOKUPP - Lookup Parent Directory</name>
<section toc="exclude" anchor="OP_LOOKUPP_ARGUMENTS" numbered="true"> <section toc="exclude" anchor="OP_LOOKUPP_ARGUMENTS" numbered="true">
<name>ARGUMENTS</name> <name>ARGUMENTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
/* CURRENT_FH: object */ /* CURRENT_FH: object */
void;]]></sourcecode> void;]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_LOOKUPP_RESULTS" numbered="true"> <section toc="exclude" anchor="OP_LOOKUPP_RESULTS" numbered="true">
<name>RESULTS</name> <name>RESULTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct LOOKUPP4res { struct LOOKUPP4res {
/* new CURRENT_FH: parent directory */ /* new CURRENT_FH: parent directory */
nfsstat4 status; nfsstat4 status;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_LOOKUPP_DESCRIPTION" numbered="true"> <section toc="exclude" anchor="OP_LOOKUPP_DESCRIPTION" numbered="true">
<name>DESCRIPTION</name> <name>DESCRIPTION</name>
<t> <t>
The current filehandle is assumed to refer to a regular The current filehandle is assumed to refer to a regular
directory or a named attribute directory. LOOKUPP assigns the directory or a named attribute directory. LOOKUPP assigns the
skipping to change at line 32350 skipping to change at line 31785
associated file, and conveying this to applications might be associated file, and conveying this to applications might be
unsafe as many applications expect the parent of an object to unsafe as many applications expect the parent of an object to
always be a directory. Therefore, the client may want to hide always be a directory. Therefore, the client may want to hide
the parent of named attribute directories (represented as ".." the parent of named attribute directories (represented as ".."
in UNIX) or represent the named attribute directory as its own in UNIX) or represent the named attribute directory as its own
parent (as is typically done for the file system root directory in parent (as is typically done for the file system root directory in
UNIX). UNIX).
</t> </t>
</section> </section>
</section> </section>
<!--[auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007-2008) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_NVERIFY" numbered="true" toc="default"> <section anchor="OP_NVERIFY" numbered="true" toc="default">
<name>Operation 17: NVERIFY - Verify Difference in Attributes</name> <name>Operation 17: NVERIFY - Verify Difference in Attributes</name>
<section toc="exclude" anchor="OP_NVERIFY_ARGUMENTS" numbered="true"> <section toc="exclude" anchor="OP_NVERIFY_ARGUMENTS" numbered="true">
<name>ARGUMENTS</name> <name>ARGUMENTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct NVERIFY4args { struct NVERIFY4args {
/* CURRENT_FH: object */ /* CURRENT_FH: object */
fattr4 obj_attributes; fattr4 obj_attributes;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_NVERIFY_RESULTS" numbered="true"> <section toc="exclude" anchor="OP_NVERIFY_RESULTS" numbered="true">
<name>RESULTS</name> <name>RESULTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct NVERIFY4res { struct NVERIFY4res {
nfsstat4 status; nfsstat4 status;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_NVERIFY_DESCRIPTION" numbered="true"> <section toc="exclude" anchor="OP_NVERIFY_DESCRIPTION" numbered="true">
<name>DESCRIPTION</name> <name>DESCRIPTION</name>
<t> <t>
This operation is used to prefix a sequence of operations to be This operation is used to prefix a sequence of operations to be
performed if one or more attributes have changed on some file system performed if one or more attributes have changed on some file system
object. If all the attributes match, then the error NFS4ERR_SAME <bcp14>MUST</bcp14> object. If all the attributes match, then the error NFS4ERR_SAME <bcp14>MUST</bcp14>
skipping to change at line 32391 skipping to change at line 31823
</section> </section>
<section toc="exclude" anchor="OP_NVERIFY_IMPLEMENTATION" numbered="true"> <section toc="exclude" anchor="OP_NVERIFY_IMPLEMENTATION" numbered="true">
<name>IMPLEMENTATION</name> <name>IMPLEMENTATION</name>
<t> <t>
This operation is useful as a cache validation operator. If the This operation is useful as a cache validation operator. If the
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:
</t> </t>
<sourcecode type=""><![CDATA[ <sourcecode type="nfsv4compound"><![CDATA[
SEQUENCE SEQUENCE
PUTFH fh PUTFH fh
NVERIFY attrbits attrs NVERIFY attrbits attrs
READ 0 32767]]></sourcecode> READ 0 32767]]></sourcecode>
<t> <t>
Contrast this with NFSv3, which would first send a GETATTR in Contrast this with NFSv3, which would first send a GETATTR in
one request/reply round trip, and then if attributes indicated that one request/reply round trip, and then if attributes indicated that
the client's cache was stale, then send a READ in another request/reply the client's cache was stale, then send a READ in another request/reply
round trip. round trip.
</t> </t>
skipping to change at line 32415 skipping to change at line 31847
file system object, the error NFS4ERR_ATTRNOTSUPP is returned to the file system object, the error NFS4ERR_ATTRNOTSUPP is returned to the
client. client.
</t> </t>
<t> <t>
When the attribute rdattr_error or any set-only attribute (e.g., When the attribute rdattr_error or any set-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.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007-2008) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_OPEN" numbered="true" toc="default"> <section anchor="OP_OPEN" numbered="true" toc="default">
<name>Operation 18: OPEN - Open a Regular File</name> <name>Operation 18: OPEN - Open a Regular File</name>
<section toc="exclude" anchor="OP_OPEN_ARGUMENTS" numbered="true"> <section toc="exclude" anchor="OP_OPEN_ARGUMENTS" numbered="true">
<name>ARGUMENTS</name> <name>ARGUMENTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
/* /*
* Various definitions for OPEN * Various definitions for OPEN
*/ */
enum createmode4 { enum createmode4 {
UNCHECKED4 = 0, UNCHECKED4 = 0,
GUARDED4 = 1, GUARDED4 = 1,
/* Deprecated in NFSv4.1. */ /* Deprecated in NFSv4.1. */
EXCLUSIVE4 = 2, EXCLUSIVE4 = 2,
/* /*
* New to NFSv4.1. If session is persistent, * New to NFSv4.1. If session is persistent,
skipping to change at line 32640 skipping to change at line 32069
seqid4 seqid; seqid4 seqid;
uint32_t share_access; uint32_t share_access;
uint32_t share_deny; uint32_t share_deny;
open_owner4 owner; open_owner4 owner;
openflag4 openhow; openflag4 openhow;
open_claim4 claim; open_claim4 claim;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_OPEN_RESULTS" numbered="true"> <section toc="exclude" anchor="OP_OPEN_RESULTS" numbered="true">
<name>RESULTS</name> <name>RESULTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct open_read_delegation4 { struct open_read_delegation4 {
stateid4 stateid; /* Stateid for delegation*/ stateid4 stateid; /* Stateid for delegation*/
bool recall; /* Pre-recalled flag for bool recall; /* Pre-recalled flag for
delegations obtained delegations obtained
by reclaim (CLAIM_PREVIOUS) */ by reclaim (CLAIM_PREVIOUS) */
nfsace4 permissions; /* Defines users who don't nfsace4 permissions; /* Defines users who don't
need an ACCESS call to need an ACCESS call to
open for read */ open for read */
}; };
skipping to change at line 33573 skipping to change at line 33002
because the server may maintain the state indefinitely as long as because the server may maintain the state indefinitely as long as
another client does not attempt to make a conflicting access to the another client does not attempt to make a conflicting access to the
same file. same file.
</t> </t>
<t> <t>
See also <xref target="COMPOUND_Sizing_Issues" format="default"/>. See also <xref target="COMPOUND_Sizing_Issues" format="default"/>.
</t> </t>
</section> </section>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_OPENATTR" numbered="true" toc="default"> <section anchor="OP_OPENATTR" numbered="true" toc="default">
<name>Operation 19: OPENATTR - Open Named Attribute Directory</name> <name>Operation 19: OPENATTR - Open Named Attribute Directory</name>
<section toc="exclude" anchor="OP_OPENATTR_ARGUMENTS" numbered="true"> <section toc="exclude" anchor="OP_OPENATTR_ARGUMENTS" numbered="true">
<name>ARGUMENTS</name> <name>ARGUMENTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct OPENATTR4args { struct OPENATTR4args {
/* CURRENT_FH: object */ /* CURRENT_FH: object */
bool createdir; bool createdir;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_OPENATTR_RESULTS" numbered="true"> <section toc="exclude" anchor="OP_OPENATTR_RESULTS" numbered="true">
<name>RESULTS</name> <name>RESULTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct OPENATTR4res { struct OPENATTR4res {
/* /*
* If status is NFS4_OK, * If status is NFS4_OK,
* new CURRENT_FH: named attribute * new CURRENT_FH: named attribute
* directory * directory
*/ */
nfsstat4 status; nfsstat4 status;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_OPENATTR_DESCRIPTION" numbered="true"> <section toc="exclude" anchor="OP_OPENATTR_DESCRIPTION" numbered="true">
skipping to change at line 33642 skipping to change at line 33068
</section> </section>
<section toc="exclude" anchor="OP_OPENATTR_IMPLEMENTATION" numbered="true"> <section toc="exclude" anchor="OP_OPENATTR_IMPLEMENTATION" numbered="true">
<name>IMPLEMENTATION</name> <name>IMPLEMENTATION</name>
<t> <t>
If the server does not support named attributes for the current If the server does not support named attributes for the current
filehandle, an error of NFS4ERR_NOTSUPP will be returned to the filehandle, an error of NFS4ERR_NOTSUPP will be returned to the
client. client.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007-2008) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_OPEN_DOWNGRADE" numbered="true" toc="default"> <section anchor="OP_OPEN_DOWNGRADE" numbered="true" toc="default">
<name>Operation 21: OPEN_DOWNGRADE - Reduce Open File Access</name> <name>Operation 21: OPEN_DOWNGRADE - Reduce Open File Access</name>
<section toc="exclude" anchor="OP_OPEN_DOWNGRADE_ARGUMENTS" numbered="true"> <section toc="exclude" anchor="OP_OPEN_DOWNGRADE_ARGUMENTS" numbered="true">
<name>ARGUMENTS</name> <name>ARGUMENTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct OPEN_DOWNGRADE4args { struct OPEN_DOWNGRADE4args {
/* CURRENT_FH: opened file */ /* CURRENT_FH: opened file */
stateid4 open_stateid; stateid4 open_stateid;
seqid4 seqid; seqid4 seqid;
uint32_t share_access; uint32_t share_access;
uint32_t share_deny; uint32_t share_deny;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_OPEN_DOWNGRADE_RESULTS" numbered="true"> <section toc="exclude" anchor="OP_OPEN_DOWNGRADE_RESULTS" numbered="true">
<name>RESULTS</name> <name>RESULTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct OPEN_DOWNGRADE4resok { struct OPEN_DOWNGRADE4resok {
stateid4 open_stateid; stateid4 open_stateid;
}; };
union OPEN_DOWNGRADE4res switch(nfsstat4 status) { union OPEN_DOWNGRADE4res switch(nfsstat4 status) {
case NFS4_OK: case NFS4_OK:
OPEN_DOWNGRADE4resok resok4; OPEN_DOWNGRADE4resok resok4;
default: default:
void; void;
};]]></sourcecode> };]]></sourcecode>
skipping to change at line 33748 skipping to change at line 33171
<section toc="exclude" anchor="OP_OPEN_DOWNGRADE_IMPLEMENTATION" numbered="true"> <section toc="exclude" anchor="OP_OPEN_DOWNGRADE_IMPLEMENTATION" numbered="true">
<name>IMPLEMENTATION</name> <name>IMPLEMENTATION</name>
<t> <t>
An OPEN_DOWNGRADE operation may make OPEN_DELEGATE_READ delegations grantable An OPEN_DOWNGRADE operation may make OPEN_DELEGATE_READ delegations grantable
where they were not previously. Servers may choose to respond where they were not previously. Servers may choose to respond
immediately if there are pending delegation want requests or may immediately if there are pending delegation want requests or may
respond to the situation at a later time. respond to the situation at a later time.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_PUTFH" numbered="true" toc="default"> <section anchor="OP_PUTFH" numbered="true" toc="default">
<name>Operation 22: PUTFH - Set Current Filehandle</name> <name>Operation 22: PUTFH - Set Current Filehandle</name>
<section toc="exclude" anchor="OP_PUTFH_ARGUMENTS" numbered="true"> <section toc="exclude" anchor="OP_PUTFH_ARGUMENTS" numbered="true">
<name>ARGUMENTS</name> <name>ARGUMENTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct PUTFH4args { struct PUTFH4args {
nfs_fh4 object; nfs_fh4 object;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_PUTFH_RESULTS" numbered="true"> <section toc="exclude" anchor="OP_PUTFH_RESULTS" numbered="true">
<name>RESULTS</name> <name>RESULTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct PUTFH4res { struct PUTFH4res {
/* /*
* If status is NFS4_OK, * If status is NFS4_OK,
* new CURRENT_FH: argument to PUTFH * new CURRENT_FH: argument to PUTFH
*/ */
nfsstat4 status; nfsstat4 status;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_PUTFH_DESCRIPTION" numbered="true"> <section toc="exclude" anchor="OP_PUTFH_DESCRIPTION" numbered="true">
<name>DESCRIPTION</name> <name>DESCRIPTION</name>
skipping to change at line 33800 skipping to change at line 33220
</section> </section>
<section toc="exclude" anchor="OP_PUTFH_IMPLEMENTATION" numbered="true"> <section toc="exclude" anchor="OP_PUTFH_IMPLEMENTATION" numbered="true">
<name>IMPLEMENTATION</name> <name>IMPLEMENTATION</name>
<t> <t>
This operation is used This operation is used
in an NFS request to set the context for file accessing operations that in an NFS request to set the context for file accessing operations that
follow in the same COMPOUND request. follow in the same COMPOUND request.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_PUTPUBFH" numbered="true" toc="default"> <section anchor="OP_PUTPUBFH" numbered="true" toc="default">
<name>Operation 23: PUTPUBFH - Set Public Filehandle</name> <name>Operation 23: PUTPUBFH - Set Public Filehandle</name>
<section toc="exclude" anchor="OP_PUTPUBFH_ARGUMENT" numbered="true"> <section toc="exclude" anchor="OP_PUTPUBFH_ARGUMENT" numbered="true">
<name>ARGUMENT</name> <name>ARGUMENT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
void; void;
]]></sourcecode> ]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_PUTPUBFH_RESULT" numbered="true"> <section toc="exclude" anchor="OP_PUTPUBFH_RESULT" numbered="true">
<name>RESULT</name> <name>RESULT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct PUTPUBFH4res { struct PUTPUBFH4res {
/* /*
* If status is NFS4_OK, * If status is NFS4_OK,
* new CURRENT_FH: public fh * new CURRENT_FH: public fh
*/ */
nfsstat4 status; nfsstat4 status;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_PUTPUBFH_DESCRIPTION" numbered="true"> <section toc="exclude" anchor="OP_PUTPUBFH_DESCRIPTION" numbered="true">
<name>DESCRIPTION</name> <name>DESCRIPTION</name>
skipping to change at line 33897 skipping to change at line 33314
This method is not available with NFSv4.1 as This method is not available with NFSv4.1 as
filehandles are not overloaded with special filehandles are not overloaded with special
meaning and therefore do not provide the same meaning and therefore do not provide the same
framework as NFSv3. Clients should therefore use framework as NFSv3. Clients should therefore use
the security negotiation mechanisms described in the security negotiation mechanisms described in
<xref target="Security_Service_Negotiation" format="default"/>. <xref target="Security_Service_Negotiation" format="default"/>.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_PUTROOTFH" numbered="true" toc="default"> <section anchor="OP_PUTROOTFH" numbered="true" toc="default">
<name>Operation 24: PUTROOTFH - Set Root Filehandle</name> <name>Operation 24: PUTROOTFH - Set Root Filehandle</name>
<section toc="exclude" anchor="OP_PUTROOTFH_ARGUMENTS" numbered="true"> <section toc="exclude" anchor="OP_PUTROOTFH_ARGUMENTS" numbered="true">
<name>ARGUMENTS</name> <name>ARGUMENTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
void;]]></sourcecode> void;]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_PUTROOTFH_RESULTS" numbered="true"> <section toc="exclude" anchor="OP_PUTROOTFH_RESULTS" numbered="true">
<name>RESULTS</name> <name>RESULTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct PUTROOTFH4res { struct PUTROOTFH4res {
/* /*
* If status is NFS4_OK, * If status is NFS4_OK,
* new CURRENT_FH: root fh * new CURRENT_FH: root fh
*/ */
nfsstat4 status; nfsstat4 status;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_PUTROOTFH_DESCRIPTION" numbered="true"> <section toc="exclude" anchor="OP_PUTROOTFH_DESCRIPTION" numbered="true">
<name>DESCRIPTION</name> <name>DESCRIPTION</name>
skipping to change at line 33948 skipping to change at line 33362
</section> </section>
<section toc="exclude" anchor="OP_PUTROOTFH_IMPLEMENTATION" numbered="true"> <section toc="exclude" anchor="OP_PUTROOTFH_IMPLEMENTATION" numbered="true">
<name>IMPLEMENTATION</name> <name>IMPLEMENTATION</name>
<t> <t>
This operation is used This operation is used
in an NFS request to set the context for file accessing operations that in an NFS request to set the context for file accessing operations that
follow in the same COMPOUND request. follow in the same COMPOUND request.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_READ" numbered="true" toc="default"> <section anchor="OP_READ" numbered="true" toc="default">
<name>Operation 25: READ - Read from File</name> <name>Operation 25: READ - Read from File</name>
<section toc="exclude" anchor="OP_READ_ARGUMENTS" numbered="true"> <section toc="exclude" anchor="OP_READ_ARGUMENTS" numbered="true">
<name>ARGUMENTS</name> <name>ARGUMENTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct READ4args { struct READ4args {
/* CURRENT_FH: file */ /* CURRENT_FH: file */
stateid4 stateid; stateid4 stateid;
offset4 offset; offset4 offset;
count4 count; count4 count;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_READ_RESULTS" numbered="true"> <section toc="exclude" anchor="OP_READ_RESULTS" numbered="true">
<name>RESULTS</name> <name>RESULTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct READ4resok { struct READ4resok {
bool eof; bool eof;
opaque data<>; opaque data<>;
}; };
union READ4res switch (nfsstat4 status) { union READ4res switch (nfsstat4 status) {
case NFS4_OK: case NFS4_OK:
READ4resok resok4; READ4resok resok4;
default: default:
void; void;
skipping to change at line 34072 skipping to change at line 33483
happens very quickly, one or more NFS4ERR_DELAY errors will be happens very quickly, one or more NFS4ERR_DELAY errors will be
returned to requests made while the delegation remains outstanding. returned to requests made while the delegation remains outstanding.
Normally, delegations will not be recalled as a result of a READ Normally, delegations will not be recalled as a result of a READ
operation since the recall will occur as a result of an earlier operation since the recall will occur as a result of an earlier
OPEN. However, since it is possible for a READ to be done with OPEN. However, since it is possible for a READ to be done with
a special stateid, the server needs to check for this case even a special stateid, the server needs to check for this case even
though the client should have done an OPEN previously. though the client should have done an OPEN previously.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_READDIR" numbered="true" toc="default"> <section anchor="OP_READDIR" numbered="true" toc="default">
<name>Operation 26: READDIR - Read Directory</name> <name>Operation 26: READDIR - Read Directory</name>
<section toc="exclude" anchor="OP_READDIR_ARGUMENTS" numbered="true"> <section toc="exclude" anchor="OP_READDIR_ARGUMENTS" numbered="true">
<name>ARGUMENTS</name> <name>ARGUMENTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct READDIR4args { struct READDIR4args {
/* CURRENT_FH: directory */ /* CURRENT_FH: directory */
nfs_cookie4 cookie; nfs_cookie4 cookie;
verifier4 cookieverf; verifier4 cookieverf;
count4 dircount; count4 dircount;
count4 maxcount; count4 maxcount;
bitmap4 attr_request; bitmap4 attr_request;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_READDIR_RESULTS" numbered="true"> <section toc="exclude" anchor="OP_READDIR_RESULTS" numbered="true">
<name>RESULTS</name> <name>RESULTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct entry4 { struct entry4 {
nfs_cookie4 cookie; nfs_cookie4 cookie;
component4 name; component4 name;
fattr4 attrs; fattr4 attrs;
entry4 *nextentry; entry4 *nextentry;
}; };
struct dirlist4 { struct dirlist4 {
entry4 *entries; entry4 *entries;
bool eof; bool eof;
skipping to change at line 34261 skipping to change at line 33669
context of its previous READDIR. context of its previous READDIR.
</t> </t>
<t> <t>
Since some servers will not be returning "." and ".." entries as has Since some servers will not be returning "." and ".." entries as has
been done with previous versions of the NFS protocol, the client that been done with previous versions of the NFS protocol, the client that
requires these entries be present in READDIR responses must fabricate requires these entries be present in READDIR responses must fabricate
them. them.
</t> </t>
</section> </section>
</section> </section>
<!--[auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_READLINK" numbered="true" toc="default"> <section anchor="OP_READLINK" numbered="true" toc="default">
<name>Operation 27: READLINK - Read Symbolic Link</name> <name>Operation 27: READLINK - Read Symbolic Link</name>
<section toc="exclude" anchor="OP_READLINK_ARGUMENTS" numbered="true"> <section toc="exclude" anchor="OP_READLINK_ARGUMENTS" numbered="true">
<name>ARGUMENTS</name> <name>ARGUMENTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
/* CURRENT_FH: symlink */ /* CURRENT_FH: symlink */
void;]]></sourcecode> void;]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_READLINK_RESULTS" numbered="true"> <section toc="exclude" anchor="OP_READLINK_RESULTS" numbered="true">
<name>RESULTS</name> <name>RESULTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct READLINK4resok { struct READLINK4resok {
linktext4 link; linktext4 link;
}; };
union READLINK4res switch (nfsstat4 status) { union READLINK4res switch (nfsstat4 status) {
case NFS4_OK: case NFS4_OK:
READLINK4resok resok4; READLINK4resok resok4;
default: default:
void; void;
};]]></sourcecode> };]]></sourcecode>
skipping to change at line 34322 skipping to change at line 33727
symbolic links, then they must agree on the interpretation of the data symbolic links, then they must agree on the interpretation of the data
in the symbolic link. in the symbolic link.
</t> </t>
<t> <t>
The READLINK operation is only allowed on objects of type NF4LNK. The READLINK operation is only allowed on objects of type NF4LNK.
The server should return the error NFS4ERR_WRONG_TYPE if the The server should return the error NFS4ERR_WRONG_TYPE if the
object is not of type NF4LNK. object is not of type NF4LNK.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_REMOVE" numbered="true" toc="default"> <section anchor="OP_REMOVE" numbered="true" toc="default">
<name>Operation 28: REMOVE - Remove File System Object</name> <name>Operation 28: REMOVE - Remove File System Object</name>
<section toc="exclude" anchor="OP_REMOVE_ARGUMENTS" numbered="true"> <section toc="exclude" anchor="OP_REMOVE_ARGUMENTS" numbered="true">
<name>ARGUMENTS</name> <name>ARGUMENTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct REMOVE4args { struct REMOVE4args {
/* CURRENT_FH: directory */ /* CURRENT_FH: directory */
component4 target; component4 target;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_REMOVE_RESULTS" numbered="true"> <section toc="exclude" anchor="OP_REMOVE_RESULTS" numbered="true">
<name>RESULTS</name> <name>RESULTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct REMOVE4resok { struct REMOVE4resok {
change_info4 cinfo; change_info4 cinfo;
}; };
union REMOVE4res switch (nfsstat4 status) { union REMOVE4res switch (nfsstat4 status) {
case NFS4_OK: case NFS4_OK:
REMOVE4resok resok4; REMOVE4resok resok4;
default: default:
void; void;
};]]></sourcecode> };]]></sourcecode>
skipping to change at line 34512 skipping to change at line 33914
if the removal happens as a separate operation. if the removal happens as a separate operation.
In the case in which the removal is integrated and In the case in which the removal is integrated and
atomic with RENAME, the notification of the removal atomic with RENAME, the notification of the removal
is integrated with notification for the RENAME. See is integrated with notification for the RENAME. See
the discussion of the NOTIFY4_RENAME_ENTRY the discussion of the NOTIFY4_RENAME_ENTRY
notification in <xref target="OP_CB_NOTIFY" format="default"/>. notification in <xref target="OP_CB_NOTIFY" format="default"/>.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_RENAME" numbered="true" toc="default"> <section anchor="OP_RENAME" numbered="true" toc="default">
<name>Operation 29: RENAME - Rename Directory Entry</name> <name>Operation 29: RENAME - Rename Directory Entry</name>
<section toc="exclude" anchor="OP_RENAME_ARGUMENTS" numbered="true"> <section toc="exclude" anchor="OP_RENAME_ARGUMENTS" numbered="true">
<name>ARGUMENTS</name> <name>ARGUMENTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct RENAME4args { struct RENAME4args {
/* SAVED_FH: source directory */ /* SAVED_FH: source directory */
component4 oldname; component4 oldname;
/* CURRENT_FH: target directory */ /* CURRENT_FH: target directory */
component4 newname; component4 newname;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_RENAME_RESULTS" numbered="true"> <section toc="exclude" anchor="OP_RENAME_RESULTS" numbered="true">
<name>RESULTS</name> <name>RESULTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct RENAME4resok { struct RENAME4resok {
change_info4 source_cinfo; change_info4 source_cinfo;
change_info4 target_cinfo; change_info4 target_cinfo;
}; };
union RENAME4res switch (nfsstat4 status) { union RENAME4res switch (nfsstat4 status) {
case NFS4_OK: case NFS4_OK:
RENAME4resok resok4; RENAME4resok resok4;
default: default:
void; void;
skipping to change at line 34728 skipping to change at line 34127
In addition, on many servers the case of oldname or newname being In addition, on many servers the case of oldname or newname being
an alias for the source directory will be checked for. Such servers an alias for the source directory will be checked for. Such servers
will return the error NFS4ERR_INVAL in these cases. will return the error NFS4ERR_INVAL in these cases.
</t> </t>
<t> <t>
If either of the source or target filehandles are not directories, the If either of the source or target filehandles are not directories, the
server will return NFS4ERR_NOTDIR. server will return NFS4ERR_NOTDIR.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_RESTOREFH" numbered="true" toc="default"> <section anchor="OP_RESTOREFH" numbered="true" toc="default">
<name>Operation 31: RESTOREFH - Restore Saved Filehandle</name> <name>Operation 31: RESTOREFH - Restore Saved Filehandle</name>
<section toc="exclude" anchor="OP_RESTOREFH_ARGUMENTS" numbered="true"> <section toc="exclude" anchor="OP_RESTOREFH_ARGUMENTS" numbered="true">
<name>ARGUMENTS</name> <name>ARGUMENTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
/* SAVED_FH: */ /* SAVED_FH: */
void;]]></sourcecode> void;]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_RESTOREFH_RESULTS" numbered="true"> <section toc="exclude" anchor="OP_RESTOREFH_RESULTS" numbered="true">
<name>RESULTS</name> <name>RESULTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct RESTOREFH4res { struct RESTOREFH4res {
/* /*
* If status is NFS4_OK, * If status is NFS4_OK,
* new CURRENT_FH: value of saved fh * new CURRENT_FH: value of saved fh
*/ */
nfsstat4 status; nfsstat4 status;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_RESTOREFH_DESCRIPTION" numbered="true"> <section toc="exclude" anchor="OP_RESTOREFH_DESCRIPTION" numbered="true">
<name>DESCRIPTION</name> <name>DESCRIPTION</name>
skipping to change at line 34777 skipping to change at line 34173
<section toc="exclude" anchor="OP_RESTOREFH_IMPLEMENTATION" numbered="true"> <section toc="exclude" anchor="OP_RESTOREFH_IMPLEMENTATION" numbered="true">
<name>IMPLEMENTATION</name> <name>IMPLEMENTATION</name>
<t> <t>
Operations like OPEN and LOOKUP use the current filehandle Operations like OPEN and LOOKUP use the current filehandle
to represent a directory and replace it with a new filehandle. to represent a directory and replace it with a new filehandle.
Assuming that the previous filehandle was saved with a SAVEFH operator, Assuming that the previous filehandle was saved with a SAVEFH operator,
the previous filehandle can be restored as the current filehandle. the previous filehandle can be restored as the current filehandle.
This is commonly used to obtain post-operation attributes for This is commonly used to obtain post-operation attributes for
the directory, e.g., the directory, e.g.,
</t> </t>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
PUTFH (directory filehandle) PUTFH (directory filehandle)
SAVEFH SAVEFH
GETATTR attrbits (pre-op dir attrs) GETATTR attrbits (pre-op dir attrs)
CREATE optbits "foo" attrs CREATE optbits "foo" attrs
GETATTR attrbits (file attributes) GETATTR attrbits (file attributes)
RESTOREFH RESTOREFH
GETATTR attrbits (post-op dir attrs)]]></sourcecode> GETATTR attrbits (post-op dir attrs)]]></sourcecode>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_SAVEFH" numbered="true" toc="default"> <section anchor="OP_SAVEFH" numbered="true" toc="default">
<name>Operation 32: SAVEFH - Save Current Filehandle</name> <name>Operation 32: SAVEFH - Save Current Filehandle</name>
<section toc="exclude" anchor="OP_SAVEFH_ARGUMENTS" numbered="true"> <section toc="exclude" anchor="OP_SAVEFH_ARGUMENTS" numbered="true">
<name>ARGUMENTS</name> <name>ARGUMENTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
/* CURRENT_FH: */ /* CURRENT_FH: */
void;]]></sourcecode> void;]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_SAVEFH_RESULTS" numbered="true"> <section toc="exclude" anchor="OP_SAVEFH_RESULTS" numbered="true">
<name>RESULTS</name> <name>RESULTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct SAVEFH4res { struct SAVEFH4res {
/* /*
* If status is NFS4_OK, * If status is NFS4_OK,
* new SAVED_FH: value of current fh * new SAVED_FH: value of current fh
*/ */
nfsstat4 status; nfsstat4 status;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_SAVEFH_DESCRIPTION" numbered="true"> <section toc="exclude" anchor="OP_SAVEFH_DESCRIPTION" numbered="true">
<name>DESCRIPTION</name> <name>DESCRIPTION</name>
skipping to change at line 34833 skipping to change at line 34226
</t> </t>
<t> <t>
See <xref target="current_stateid" format="default"/> for more details on the current See <xref target="current_stateid" format="default"/> for more details on the current
stateid. stateid.
</t> </t>
</section> </section>
<section toc="exclude" anchor="OP_SAVEFH_IMPLEMENTATION" numbered="true"> <section toc="exclude" anchor="OP_SAVEFH_IMPLEMENTATION" numbered="true">
<name>IMPLEMENTATION</name> <name>IMPLEMENTATION</name>
</section> </section>
</section> </section>
<!--[auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007-2008) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_SECINFO" numbered="true" toc="default"> <section anchor="OP_SECINFO" numbered="true" toc="default">
<name>Operation 33: SECINFO - Obtain Available Security</name> <name>Operation 33: SECINFO - Obtain Available Security</name>
<section toc="exclude" anchor="OP_SECINFO_ARGUMENTS" numbered="true"> <section toc="exclude" anchor="OP_SECINFO_ARGUMENTS" numbered="true">
<name>ARGUMENTS</name> <name>ARGUMENTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct SECINFO4args { struct SECINFO4args {
/* CURRENT_FH: directory */ /* CURRENT_FH: directory */
component4 name; component4 name;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_SECINFO_RESULTS" numbered="true"> <section toc="exclude" anchor="OP_SECINFO_RESULTS" numbered="true">
<name>RESULTS</name> <name>RESULTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
/* /*
* From RFC 2203 * From RFC 2203
*/ */
enum rpc_gss_svc_t { enum rpc_gss_svc_t {
RPC_GSS_SVC_NONE = 1, RPC_GSS_SVC_NONE = 1,
RPC_GSS_SVC_INTEGRITY = 2, RPC_GSS_SVC_INTEGRITY = 2,
RPC_GSS_SVC_PRIVACY = 3 RPC_GSS_SVC_PRIVACY = 3
}; };
struct rpcsec_gss_info { struct rpcsec_gss_info {
skipping to change at line 35063 skipping to change at line 34453
</li> </li>
</ul> </ul>
<t> <t>
See <xref target="SECCON" format="default"/> for a discussion on See <xref target="SECCON" format="default"/> for a discussion on
the recommendations for the security flavor used by SECINFO and the recommendations for the security flavor used by SECINFO and
SECINFO_NO_NAME. SECINFO_NO_NAME.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_SETATTR" numbered="true" toc="default"> <section anchor="OP_SETATTR" numbered="true" toc="default">
<name>Operation 34: SETATTR - Set Attributes</name> <name>Operation 34: SETATTR - Set Attributes</name>
<section toc="exclude" anchor="OP_SETATTR_ARGUMENTS" numbered="true"> <section toc="exclude" anchor="OP_SETATTR_ARGUMENTS" numbered="true">
<name>ARGUMENTS</name> <name>ARGUMENTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct SETATTR4args { struct SETATTR4args {
/* CURRENT_FH: target object */ /* CURRENT_FH: target object */
stateid4 stateid; stateid4 stateid;
fattr4 obj_attributes; fattr4 obj_attributes;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_SETATTR_RESULTS" numbered="true"> <section toc="exclude" anchor="OP_SETATTR_RESULTS" numbered="true">
<name>RESULTS</name> <name>RESULTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct SETATTR4res { struct SETATTR4res {
nfsstat4 status; nfsstat4 status;
bitmap4 attrsset; bitmap4 attrsset;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_SETATTR_DESCRIPTION" numbered="true"> <section toc="exclude" anchor="OP_SETATTR_DESCRIPTION" numbered="true">
<name>DESCRIPTION</name> <name>DESCRIPTION</name>
<t> <t>
The SETATTR operation changes one or more of the attributes of a The SETATTR operation changes one or more of the attributes of a
file system object. The new attributes are specified with a bitmap and file system object. The new attributes are specified with a bitmap and
skipping to change at line 35231 skipping to change at line 34618
</t> </t>
<t> <t>
A mask of the attributes actually set is returned by SETATTR in all A mask of the attributes actually set is returned by SETATTR in all
cases. That mask <bcp14>MUST NOT</bcp14> include attribute bits not requested to be cases. That mask <bcp14>MUST NOT</bcp14> include attribute bits not requested to be
set by the client. set by the client.
If the attribute masks in the request and If the attribute masks in the request and
reply are equal, the status field in the reply <bcp14>MUST</bcp14> be NFS4_OK. reply are equal, the status field in the reply <bcp14>MUST</bcp14> be NFS4_OK.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007-2008) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_VERIFY" numbered="true" toc="default"> <section anchor="OP_VERIFY" numbered="true" toc="default">
<name>Operation 37: VERIFY - Verify Same Attributes</name> <name>Operation 37: VERIFY - Verify Same Attributes</name>
<section toc="exclude" anchor="OP_VERIFY_ARGUMENTS" numbered="true"> <section toc="exclude" anchor="OP_VERIFY_ARGUMENTS" numbered="true">
<name>ARGUMENTS</name> <name>ARGUMENTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct VERIFY4args { struct VERIFY4args {
/* CURRENT_FH: object */ /* CURRENT_FH: object */
fattr4 obj_attributes; fattr4 obj_attributes;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_VERIFY_RESULTS" numbered="true"> <section toc="exclude" anchor="OP_VERIFY_RESULTS" numbered="true">
<name>RESULTS</name> <name>RESULTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct VERIFY4res { struct VERIFY4res {
nfsstat4 status; nfsstat4 status;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_VERIFY_DESCRIPTION" numbered="true"> <section toc="exclude" anchor="OP_VERIFY_DESCRIPTION" numbered="true">
<name>DESCRIPTION</name> <name>DESCRIPTION</name>
<t> <t>
The VERIFY operation is used to verify that attributes have the value The VERIFY operation is used to verify that attributes have the value
assumed by the client before proceeding with the following operations in assumed by the client before proceeding with the following operations in
the COMPOUND request. If any of the attributes do not match, then the the COMPOUND request. If any of the attributes do not match, then the
skipping to change at line 35269 skipping to change at line 34653
</t> </t>
</section> </section>
<section toc="exclude" anchor="OP_VERIFY_IMPLEMENTATION" numbered="true"> <section toc="exclude" anchor="OP_VERIFY_IMPLEMENTATION" numbered="true">
<name>IMPLEMENTATION</name> <name>IMPLEMENTATION</name>
<t> <t>
One possible use of the VERIFY operation is the following series One possible use of the VERIFY operation is the following series
of operations. With this, the client is attempting to verify that the file of operations. With this, the client is attempting to verify that the file
being removed will match what the client expects to be removed. This being removed will match what the client expects to be removed. This
series can help prevent the unintended deletion of a file. series can help prevent the unintended deletion of a file.
</t> </t>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
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)]]></sourcecode> REMOVE (file name)]]></sourcecode>
<t> <t>
This series does not prevent a second client from removing and This series 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.
</t> </t>
skipping to change at line 35293 skipping to change at line 34677
file system object, the error NFS4ERR_ATTRNOTSUPP is returned to the file system object, the error NFS4ERR_ATTRNOTSUPP is returned to the
client. client.
</t> </t>
<t> <t>
When the attribute rdattr_error or any set-only attribute (e.g., When the attribute rdattr_error or any set-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.
</t> </t>
</section> </section>
</section> </section>
<!--[auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007-2008) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_WRITE" numbered="true" toc="default"> <section anchor="OP_WRITE" numbered="true" toc="default">
<name>Operation 38: WRITE - Write to File</name> <name>Operation 38: WRITE - Write to File</name>
<section toc="exclude" anchor="OP_WRITE_ARGUMENTS" numbered="true"> <section toc="exclude" anchor="OP_WRITE_ARGUMENTS" numbered="true">
<name>ARGUMENTS</name> <name>ARGUMENTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
enum stable_how4 { enum stable_how4 {
UNSTABLE4 = 0, UNSTABLE4 = 0,
DATA_SYNC4 = 1, DATA_SYNC4 = 1,
FILE_SYNC4 = 2 FILE_SYNC4 = 2
}; };
struct WRITE4args { struct WRITE4args {
/* CURRENT_FH: file */ /* CURRENT_FH: file */
stateid4 stateid; stateid4 stateid;
offset4 offset; offset4 offset;
stable_how4 stable; stable_how4 stable;
opaque data<>; opaque data<>;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_WRITE_RESULTS" numbered="true"> <section toc="exclude" anchor="OP_WRITE_RESULTS" numbered="true">
<name>RESULTS</name> <name>RESULTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct WRITE4resok { struct WRITE4resok {
count4 count; count4 count;
stable_how4 committed; stable_how4 committed;
verifier4 writeverf; verifier4 writeverf;
}; };
union WRITE4res switch (nfsstat4 status) { union WRITE4res switch (nfsstat4 status) {
case NFS4_OK: case NFS4_OK:
WRITE4resok resok4; WRITE4resok resok4;
default: default:
skipping to change at line 35584 skipping to change at line 34965
happens very quickly, one or more NFS4ERR_DELAY errors will be happens very quickly, one or more NFS4ERR_DELAY errors will be
returned to requests made while the delegation remains outstanding. returned to requests made while the delegation remains outstanding.
Normally, delegations will not be recalled as a result of a WRITE Normally, delegations will not be recalled as a result of a WRITE
operation since the recall will occur as a result of an earlier operation since the recall will occur as a result of an earlier
OPEN. However, since it is possible for a WRITE to be done with OPEN. However, since it is possible for a WRITE to be done with
a special stateid, the server needs to check for this case even a special stateid, the server needs to check for this case even
though the client should have done an OPEN previously. though the client should have done an OPEN previously.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007-2008) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_BACKCHANNEL_CTL" numbered="true" toc="default"> <section anchor="OP_BACKCHANNEL_CTL" numbered="true" toc="default">
<name>Operation 40: BACKCHANNEL_CTL - Backchannel Control</name> <name>Operation 40: BACKCHANNEL_CTL - Backchannel Control</name>
<section toc="exclude" anchor="OP_BACKCHANNEL_CTL_ARGUMENT" numbered="true"> <section toc="exclude" anchor="OP_BACKCHANNEL_CTL_ARGUMENT" numbered="true">
<name>ARGUMENT</name> <name>ARGUMENT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
typedef opaque gsshandle4_t<>; typedef opaque gsshandle4_t<>;
struct gss_cb_handles4 { struct gss_cb_handles4 {
rpc_gss_svc_t gcbp_service; /* RFC 2203 */ rpc_gss_svc_t gcbp_service; /* RFC 2203 */
gsshandle4_t gcbp_handle_from_server; gsshandle4_t gcbp_handle_from_server;
gsshandle4_t gcbp_handle_from_client; gsshandle4_t gcbp_handle_from_client;
}; };
union callback_sec_parms4 switch (uint32_t cb_secflavor) { union callback_sec_parms4 switch (uint32_t cb_secflavor) {
case AUTH_NONE: case AUTH_NONE:
void; void;
case AUTH_SYS: case AUTH_SYS:
authsys_parms cbsp_sys_cred; /* RFC 1831 */ authsys_parms cbsp_sys_cred; /* RFC 5531 */
case RPCSEC_GSS: case RPCSEC_GSS:
gss_cb_handles4 cbsp_gss_handles; gss_cb_handles4 cbsp_gss_handles;
}; };
struct BACKCHANNEL_CTL4args { struct BACKCHANNEL_CTL4args {
uint32_t bca_cb_program; uint32_t bca_cb_program;
callback_sec_parms4 bca_sec_parms<>; callback_sec_parms4 bca_sec_parms<>;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_BACKCHANNEL_CTL_RESULT" numbered="true"> <section toc="exclude" anchor="OP_BACKCHANNEL_CTL_RESULT" numbered="true">
<name>RESULT</name> <name>RESULT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct BACKCHANNEL_CTL4res { struct BACKCHANNEL_CTL4res {
nfsstat4 bcr_status; nfsstat4 bcr_status;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_BACKCHANNEL_CTL_DESCRIPTION" numbered="true"> <section toc="exclude" anchor="OP_BACKCHANNEL_CTL_DESCRIPTION" numbered="true">
<name>DESCRIPTION</name> <name>DESCRIPTION</name>
<t> <t>
The BACKCHANNEL_CTL operation replaces the The BACKCHANNEL_CTL operation replaces the
backchannel's callback program number and adds backchannel's callback program number and adds
(not replaces) RPCSEC_GSS handles for use by the (not replaces) RPCSEC_GSS handles for use by the
skipping to change at line 35657 skipping to change at line 35035
gcbp_handle_from_server does not exist on the server, gcbp_handle_from_server does not exist on the server,
the server <bcp14>MUST</bcp14> return NFS4ERR_NOENT. the server <bcp14>MUST</bcp14> return NFS4ERR_NOENT.
</t> </t>
<t> <t>
If an RPCSEC_GSS handle is using the SSV context (see <xref target="ssv_mech" format="default"/>), then because each SSV RPCSEC_GSS If an RPCSEC_GSS handle is using the SSV context (see <xref target="ssv_mech" format="default"/>), then because each SSV RPCSEC_GSS
handle shares a common SSV GSS context, there are security handle shares a common SSV GSS context, there are security
considerations specific to this situation discussed in <xref target="rpcsec_ssv_consider" format="default"/>. considerations specific to this situation discussed in <xref target="rpcsec_ssv_consider" format="default"/>.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007-2008) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_BIND_CONN_TO_SESSION" numbered="true" toc="default"> <section anchor="OP_BIND_CONN_TO_SESSION" numbered="true" toc="default">
<name>Operation 41: BIND_CONN_TO_SESSION - Associate Connection with Session</name> <name>Operation 41: BIND_CONN_TO_SESSION - Associate Connection with Session</name>
<section toc="exclude" anchor="OP_BIND_CONN_TO_SESSION_ARGUMENT" numbered="true"> <section toc="exclude" anchor="OP_BIND_CONN_TO_SESSION_ARGUMENT" numbered="true">
<name>ARGUMENT</name> <name>ARGUMENT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
enum channel_dir_from_client4 { enum channel_dir_from_client4 {
CDFC4_FORE = 0x1, CDFC4_FORE = 0x1,
CDFC4_BACK = 0x2, CDFC4_BACK = 0x2,
CDFC4_FORE_OR_BOTH = 0x3, CDFC4_FORE_OR_BOTH = 0x3,
CDFC4_BACK_OR_BOTH = 0x7 CDFC4_BACK_OR_BOTH = 0x7
}; };
struct BIND_CONN_TO_SESSION4args { struct BIND_CONN_TO_SESSION4args {
sessionid4 bctsa_sessid; sessionid4 bctsa_sessid;
channel_dir_from_client4 channel_dir_from_client4
bctsa_dir; bctsa_dir;
bool bctsa_use_conn_in_rdma_mode; bool bctsa_use_conn_in_rdma_mode;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_BIND_CONN_TO_SESSION_RESULT" numbered="true"> <section toc="exclude" anchor="OP_BIND_CONN_TO_SESSION_RESULT" numbered="true">
<name>RESULT</name> <name>RESULT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
enum channel_dir_from_server4 { enum channel_dir_from_server4 {
CDFS4_FORE = 0x1, CDFS4_FORE = 0x1,
CDFS4_BACK = 0x2, CDFS4_BACK = 0x2,
CDFS4_BOTH = 0x3 CDFS4_BOTH = 0x3
}; };
struct BIND_CONN_TO_SESSION4resok { struct BIND_CONN_TO_SESSION4resok {
sessionid4 bctsr_sessid; sessionid4 bctsr_sessid;
channel_dir_from_server4 channel_dir_from_server4
skipping to change at line 35838 skipping to change at line 35213
The attempted BIND_CONN_TO_SESSION with the old SSV The attempted BIND_CONN_TO_SESSION with the old SSV
should succeed. If so, the client re-sends the original should succeed. If so, the client re-sends the original
SET_SSV. If the original SET_SSV was not executed, then the SET_SSV. If the original SET_SSV was not executed, then the
server executes it. If the original SET_SSV was executed but server executes it. If the original SET_SSV was executed but
failed, the server will return the SET_SSV from the reply failed, the server will return the SET_SSV from the reply
cache. cache.
</li> </li>
</ul> </ul>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007-2008) -->
<section anchor="OP_EXCHANGE_ID" numbered="true" toc="default"> <section anchor="OP_EXCHANGE_ID" numbered="true" toc="default">
<name>Operation 42: EXCHANGE_ID - Instantiate Client ID</name> <name>Operation 42: EXCHANGE_ID - Instantiate Client ID</name>
<t> <t>
The EXCHANGE_ID operation exchanges long-hand client and server identifiers The EXCHANGE_ID operation exchanges long-hand client and server identifiers
(owners) and provides access to a client ID, creating one (owners) and provides access to a client ID, creating one
if necessary. This client ID becomes associated with the connection if necessary. This client ID becomes associated with the connection
on which the operation is done, so that it is available when a on which the operation is done, so that it is available when a
CREATE_SESSION is done or when the connection is used to issue CREATE_SESSION is done or when the connection is used to issue
a request a request
on an existing session associated with the current client. on an existing session associated with the current client.
</t> </t>
<section anchor="EXID-arg" toc="exclude" numbered="true"> <section anchor="EXID-arg" toc="exclude" numbered="true">
<name>ARGUMENT</name> <name>ARGUMENT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
const EXCHGID4_FLAG_SUPP_MOVED_REFER = 0x00000001; const EXCHGID4_FLAG_SUPP_MOVED_REFER = 0x00000001;
const EXCHGID4_FLAG_SUPP_MOVED_MIGR = 0x00000002; const EXCHGID4_FLAG_SUPP_MOVED_MIGR = 0x00000002;
const EXCHGID4_FLAG_BIND_PRINC_STATEID = 0x00000100; const EXCHGID4_FLAG_BIND_PRINC_STATEID = 0x00000100;
const EXCHGID4_FLAG_USE_NON_PNFS = 0x00010000; const EXCHGID4_FLAG_USE_NON_PNFS = 0x00010000;
const EXCHGID4_FLAG_USE_PNFS_MDS = 0x00020000; const EXCHGID4_FLAG_USE_PNFS_MDS = 0x00020000;
const EXCHGID4_FLAG_USE_PNFS_DS = 0x00040000; const EXCHGID4_FLAG_USE_PNFS_DS = 0x00040000;
const EXCHGID4_FLAG_MASK_PNFS = 0x00070000; const EXCHGID4_FLAG_MASK_PNFS = 0x00070000;
skipping to change at line 35905 skipping to change at line 35278
struct EXCHANGE_ID4args { struct EXCHANGE_ID4args {
client_owner4 eia_clientowner; client_owner4 eia_clientowner;
uint32_t eia_flags; uint32_t eia_flags;
state_protect4_a eia_state_protect; state_protect4_a eia_state_protect;
nfs_impl_id4 eia_client_impl_id<1>; nfs_impl_id4 eia_client_impl_id<1>;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section anchor="EXID-res" toc="exclude" numbered="true"> <section anchor="EXID-res" toc="exclude" numbered="true">
<name>RESULT</name> <name>RESULT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct ssv_prot_info4 { struct ssv_prot_info4 {
state_protect_ops4 spi_ops; state_protect_ops4 spi_ops;
uint32_t spi_hash_alg; uint32_t spi_hash_alg;
uint32_t spi_encr_alg; uint32_t spi_encr_alg;
uint32_t spi_ssv_len; uint32_t spi_ssv_len;
uint32_t spi_window; uint32_t spi_window;
gsshandle4_t spi_handles<>; gsshandle4_t spi_handles<>;
}; };
union state_protect4_r switch(state_protect_how4 spr_how) { union state_protect4_r switch(state_protect_how4 spr_how) {
skipping to change at line 35944 skipping to change at line 35317
union EXCHANGE_ID4res switch (nfsstat4 eir_status) { union EXCHANGE_ID4res switch (nfsstat4 eir_status) {
case NFS4_OK: case NFS4_OK:
EXCHANGE_ID4resok eir_resok4; EXCHANGE_ID4resok eir_resok4;
default: default:
void; void;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section anchor="OP_EXCHANGE_ID_DESCRIPTION" toc="exclude" numbered="true"> <section anchor="OP_EXCHANGE_ID_DESCRIPTION" toc="exclude" numbered="true">
<name>DESCRIPTION</name> <name>DESCRIPTION</name>
<!-- [rfced] In Section 18.35.3, should "client_owner" be
"client_owner4" instead (defined in 18.35.1)?
Current:
The client uses the EXCHANGE_ID operation to register
a particular client_owner with the server.
<t> <t>
The client uses the EXCHANGE_ID operation to register The client uses the EXCHANGE_ID operation to register
a particular client_owner with the server. However, a particular instance of that client with the server,
when the client_owner has already been registered as represented by a client_owner4. However,
when the client_owner4 has already been registered
by other means (e.g., Transparent State Migration), the by other means (e.g., Transparent State Migration), the
client may still use EXCHANGE_ID to obtain the client ID client may still use EXCHANGE_ID to obtain the client ID
assigned previously. assigned previously.
</t> </t>
<t> <t>
The client ID returned from this The client ID returned from this
operation will be associated with the connection operation will be associated with the connection
on which the EXCHANGE_ID is received and on which the EXCHANGE_ID is received and
will serve as a parent object for will serve as a parent object for
sessions created by the client on this connection or sessions created by the client on this connection or
to which the connection is bound. As a result of using to which the connection is bound. As a result of using
those sessions to make requests involving the creation those sessions to make requests involving the creation
of state, that state will become associated with the of state, that state will become associated with the
skipping to change at line 36344 skipping to change at line 35711
ID property, the effect applies only to new ID property, the effect applies only to new
stateids. Existing stateids (and all stateids with stateids. Existing stateids (and all stateids with
the same "other" field) that were created with the same "other" field) that were created with
stateid to principal binding in force will continue stateid to principal binding in force will continue
to have binding in force. Existing stateids (and all to have binding in force. Existing stateids (and all
stateids with the same "other" field) that were created stateids with the same "other" field) that were created
with stateid to principal not in force will continue with stateid to principal not in force will continue
to have binding not in force. to have binding not in force.
</t> </t>
<!-- [rfced] The following cross reference in Section 18.35.3
doesn't appear to be accurate. Perhaps Section 13.1 is meant
instead?
Current:
The EXCHGID4_FLAG_USE_NON_PNFS, EXCHGID4_FLAG_USE_PNFS_MDS,
and EXCHGID4_FLAG_USE_PNFS_DS bits are described in
Section 2.10.2.2 and convey roles the client ID is to be
used for in a pNFS environment.
<t> <t>
The EXCHGID4_FLAG_USE_NON_PNFS, The EXCHGID4_FLAG_USE_NON_PNFS,
EXCHGID4_FLAG_USE_PNFS_MDS, and EXCHGID4_FLAG_USE_PNFS_MDS, and
EXCHGID4_FLAG_USE_PNFS_DS bits are described in EXCHGID4_FLAG_USE_PNFS_DS bits are described in
<xref target="Client_ID_and_Session_Association" format="default"/> and convey roles the <xref target="pnfs_session_stuff"/>
and convey roles the
client ID is to be used for in a pNFS environment. client ID is to be used for in a pNFS environment.
The server <bcp14>MUST</bcp14> set one of the acceptable combinations The server <bcp14>MUST</bcp14> set one of the acceptable combinations
of these bits (roles) in eir_flags, as specified in that of these bits (roles) in eir_flags, as specified in that
section. section.
Note that the same client owner/server owner pair can Note that the same client owner/server owner pair can
have multiple roles. Multiple roles can be associated have multiple roles. Multiple roles can be associated
with the same client ID or with different client with the same client ID or with different client
IDs. Thus, if a client sends EXCHANGE_ID from the IDs. Thus, if a client sends EXCHANGE_ID from the
same client owner to the same server owner multiple same client owner to the same server owner multiple
times, but specifies different pNFS roles each time, times, but specifies different pNFS roles each time,
skipping to change at line 36751 skipping to change at line 36109
</t> </t>
<t>A private field on the server indicating whether or not a <t>A private field on the server indicating whether or not a
client record has been confirmed. A client record is client record has been confirmed. A client record is
confirmed if there has been a successful CREATE_SESSION confirmed if there has been a successful CREATE_SESSION
operation to confirm it. Otherwise, it is unconfirmed. An operation to confirm it. Otherwise, it is unconfirmed. An
unconfirmed record is established by an EXCHANGE_ID call. unconfirmed record is established by an EXCHANGE_ID call.
Any unconfirmed record that is not confirmed within a lease Any unconfirmed record that is not confirmed within a lease
period <bcp14>SHOULD</bcp14> be removed.</t> period <bcp14>SHOULD</bcp14> be removed.</t>
</li> </li>
</ol> </ol>
<!-- [auth] start new list -->
<t> <t>
The following identifiers represent special values for the fields The following identifiers represent special values for the fields
in the records. in the records.
</t> </t>
<dl newline="true" spacing="normal"> <dl newline="true" spacing="normal">
<dt>ownerid_arg:</dt> <dt>ownerid_arg:</dt>
<dd> <dd>
The value of the eia_clientowner.co_ownerid subfield of the The value of the eia_clientowner.co_ownerid subfield of the
EXCHANGE_ID4args structure of the current request. EXCHANGE_ID4args structure of the current request.
</dd> </dd>
skipping to change at line 37079 skipping to change at line 36436
</t> </t>
<t> <t>
The server returns NFS4ERR_PERM and leaves the client record The server returns NFS4ERR_PERM and leaves the client record
intact. intact.
</t> </t>
</li> </li>
</ol> </ol>
</section> </section>
</section> </section>
<!-- [auth] Copyright (C) The Internet Society (2006) -->
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007-2008) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_CREATE_SESSION" numbered="true" toc="default"> <section anchor="OP_CREATE_SESSION" numbered="true" toc="default">
<name>Operation 43: CREATE_SESSION - Create New Session and Confirm Client ID</name> <name>Operation 43: CREATE_SESSION - Create New Session and Confirm Client ID</name>
<section toc="exclude" anchor="OP_CREATE_SESSION_ARGUMENT" numbered="true"> <section toc="exclude" anchor="OP_CREATE_SESSION_ARGUMENT" numbered="true">
<name>ARGUMENT</name> <name>ARGUMENT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct channel_attrs4 { struct channel_attrs4 {
count4 ca_headerpadsize; count4 ca_headerpadsize;
count4 ca_maxrequestsize; count4 ca_maxrequestsize;
count4 ca_maxresponsesize; count4 ca_maxresponsesize;
count4 ca_maxresponsesize_cached; count4 ca_maxresponsesize_cached;
count4 ca_maxoperations; count4 ca_maxoperations;
count4 ca_maxrequests; count4 ca_maxrequests;
uint32_t ca_rdma_ird<1>; uint32_t ca_rdma_ird<1>;
}; };
skipping to change at line 37117 skipping to change at line 36470
channel_attrs4 csa_fore_chan_attrs; channel_attrs4 csa_fore_chan_attrs;
channel_attrs4 csa_back_chan_attrs; channel_attrs4 csa_back_chan_attrs;
uint32_t csa_cb_program; uint32_t csa_cb_program;
callback_sec_parms4 csa_sec_parms<>; callback_sec_parms4 csa_sec_parms<>;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_CREATE_SESSION_RESULT" numbered="true"> <section toc="exclude" anchor="OP_CREATE_SESSION_RESULT" numbered="true">
<name>RESULT</name> <name>RESULT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct CREATE_SESSION4resok { struct CREATE_SESSION4resok {
sessionid4 csr_sessionid; sessionid4 csr_sessionid;
sequenceid4 csr_sequence; sequenceid4 csr_sequence;
uint32_t csr_flags; uint32_t csr_flags;
channel_attrs4 csr_fore_chan_attrs; channel_attrs4 csr_fore_chan_attrs;
channel_attrs4 csr_back_chan_attrs; channel_attrs4 csr_back_chan_attrs;
}; };
skipping to change at line 37265 skipping to change at line 36618
CREATE_SESSION4_FLAG_CONN_RDMA in the result CREATE_SESSION4_FLAG_CONN_RDMA in the result
field csr_flags. If CREATE_SESSION4_FLAG_CONN_RDMA is field csr_flags. If CREATE_SESSION4_FLAG_CONN_RDMA is
not set in csa_flags, then CREATE_SESSION4_FLAG_CONN_RDMA <bcp14>MUST not set in csa_flags, then CREATE_SESSION4_FLAG_CONN_RDMA <bcp14>MUST
NOT</bcp14> be set in csr_flags. NOT</bcp14> be set in csr_flags.
Note that once the server agrees to step up, it and the client Note that once the server agrees to step up, it and the client
<bcp14>MUST</bcp14> exchange all future traffic on the connection with RPC RDMA <bcp14>MUST</bcp14> exchange all future traffic on the connection with RPC RDMA
framing and not Record Marking (<xref target="RFC8166" format="default"/>). framing and not Record Marking (<xref target="RFC8166" format="default"/>).
</dd> </dd>
</dl> </dl>
</dd> </dd>
<dt>csa_fore_chan_attrs, csa_fore_chan_attrs:</dt> <dt>csa_fore_chan_attrs, csa_back_chan_attrs:</dt>
<dd> <dd>
<t> <t>
The csa_fore_chan_attrs and csa_back_chan_attrs The csa_fore_chan_attrs and csa_back_chan_attrs
fields apply to attributes of the fields apply to attributes of the
fore channel (which conveys fore channel (which conveys
requests originating from the client to the server), requests originating from the client to the server),
and the backchannel (the channel that conveys and the backchannel (the channel that conveys
callback requests originating from the callback requests originating from the
server to the client), respectively. The results are in corresponding structures server to the client), respectively. The results are in corresponding structures
called csr_fore_chan_attrs and csr_back_chan_attrs. called csr_fore_chan_attrs and csr_back_chan_attrs.
skipping to change at line 37494 skipping to change at line 36847
<xref target="RFC2203" sectionFormat="bare" section="5.3.1"/> of <xref target="RFC2203" sectionFormat="bare" section="5.3.1"/> of
<xref target="RFC2203" format="default"/>). <xref target="RFC2203" format="default"/>).
</t> </t>
<t> <t>
If an RPCSEC_GSS handle is using the SSV context (see <xref target="ssv_mech" format="default"/>), then because each SSV RPCSEC_GSS If an RPCSEC_GSS handle is using the SSV context (see <xref target="ssv_mech" format="default"/>), then because each SSV RPCSEC_GSS
handle shares a common SSV GSS context, there are security handle shares a common SSV GSS context, there are security
considerations specific to this situation discussed in <xref target="rpcsec_ssv_consider" format="default"/>. considerations specific to this situation discussed in <xref target="rpcsec_ssv_consider" format="default"/>.
</t> </t>
</dd> </dd>
</dl> </dl>
<!-- [auth] sg check -->
<t> <t>
Once the session is created, the first SEQUENCE or Once the session is created, the first SEQUENCE or
CB_SEQUENCE received on a slot <bcp14>MUST</bcp14> have a sequence CB_SEQUENCE received on a slot <bcp14>MUST</bcp14> have a sequence
ID equal to 1; if not, the replier <bcp14>MUST</bcp14> return ID equal to 1; if not, the replier <bcp14>MUST</bcp14> return
NFS4ERR_SEQ_MISORDERED. NFS4ERR_SEQ_MISORDERED.
</t> </t>
</section> </section>
<section toc="exclude" anchor="OP_CREATE_SESSION_IMPLEMENTATION" numbered="true"> <section toc="exclude" anchor="OP_CREATE_SESSION_IMPLEMENTATION" numbered="true">
<name>IMPLEMENTATION</name> <name>IMPLEMENTATION</name>
skipping to change at line 37787 skipping to change at line 37139
The reference count would be incremented. The reference count would be incremented.
</li> </li>
<li> <li>
Replacing calls from RPCSEC_GSS that free GSS-API Replacing calls from RPCSEC_GSS that free GSS-API
contexts, with calls to decrement the reference count contexts, with calls to decrement the reference count
on the wrapper data structure. on the wrapper data structure.
</li> </li>
</ul> </ul>
</section> </section>
</section> </section>
<!--[auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007-2008) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_DESTROY_SESSION" numbered="true" toc="default"> <section anchor="OP_DESTROY_SESSION" numbered="true" toc="default">
<name>Operation 44: DESTROY_SESSION - Destroy a Session</name> <name>Operation 44: DESTROY_SESSION - Destroy a Session</name>
<section toc="exclude" anchor="OP_DESTROY_SESSION_ARGUMENT" numbered="true"> <section toc="exclude" anchor="OP_DESTROY_SESSION_ARGUMENT" numbered="true">
<name>ARGUMENT</name> <name>ARGUMENT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct DESTROY_SESSION4args { struct DESTROY_SESSION4args {
sessionid4 dsa_sessionid; sessionid4 dsa_sessionid;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_DESTROY_SESSION_RESULT" numbered="true"> <section toc="exclude" anchor="OP_DESTROY_SESSION_RESULT" numbered="true">
<name>RESULT</name> <name>RESULT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct DESTROY_SESSION4res { struct DESTROY_SESSION4res {
nfsstat4 dsr_status; nfsstat4 dsr_status;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_DESTROY_SESSION_DESCRIPTION" numbered="true"> <section toc="exclude" anchor="OP_DESTROY_SESSION_DESCRIPTION" numbered="true">
<name>DESCRIPTION</name> <name>DESCRIPTION</name>
<t> <t>
The DESTROY_SESSION operation closes the session and discards The DESTROY_SESSION operation closes the session and discards
the session's reply cache, if any. the session's reply cache, if any.
Any remaining connections associated with the session are Any remaining connections associated with the session are
skipping to change at line 37891 skipping to change at line 37240
the server will allow the session to be destroyed. the server will allow the session to be destroyed.
Otherwise, the error CB_BACK_CHAN_BUSY <bcp14>SHOULD</bcp14> be Otherwise, the error CB_BACK_CHAN_BUSY <bcp14>SHOULD</bcp14> be
returned to indicate that there are CB_COMPOUNDs returned to indicate that there are CB_COMPOUNDs
that need to be replied to. The client <bcp14>SHOULD</bcp14> reply that need to be replied to. The client <bcp14>SHOULD</bcp14> reply
to all outstanding CB_COMPOUNDs before re-sending to all outstanding CB_COMPOUNDs before re-sending
DESTROY_SESSION. DESTROY_SESSION.
</t> </t>
</section> </section>
</section> </section>
<!--[auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_FREE_STATEID" numbered="true" toc="default"> <section anchor="OP_FREE_STATEID" numbered="true" toc="default">
<name>Operation 45: FREE_STATEID - Free Stateid with No Locks</name> <name>Operation 45: FREE_STATEID - Free Stateid with No Locks</name>
<section toc="exclude" anchor="OP_FREE_STATEID_ARGUMENT" numbered="true"> <section toc="exclude" anchor="OP_FREE_STATEID_ARGUMENT" numbered="true">
<name>ARGUMENT</name> <name>ARGUMENT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct FREE_STATEID4args { struct FREE_STATEID4args {
stateid4 fsa_stateid; stateid4 fsa_stateid;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_FREE_STATID_RESULT" numbered="true"> <section toc="exclude" anchor="OP_FREE_STATID_RESULT" numbered="true">
<name>RESULT</name> <name>RESULT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct FREE_STATEID4res { struct FREE_STATEID4res {
nfsstat4 fsr_status; nfsstat4 fsr_status;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_FREE_STATEID4_DESCRIPTION" numbered="true"> <section toc="exclude" anchor="OP_FREE_STATEID4_DESCRIPTION" numbered="true">
<name>DESCRIPTION</name> <name>DESCRIPTION</name>
<t> <t>
The FREE_STATEID operation is used to free a stateid that no longer The FREE_STATEID operation is used to free a stateid that no longer
has any associated locks (including opens, byte-range locks, delegations, has any associated locks (including opens, byte-range locks, delegations,
and layouts). This may be because of client LOCKU operations or because and layouts). This may be because of client LOCKU operations or because
skipping to change at line 37935 skipping to change at line 37281
to allow that client again to reclaim locks, without encountering to allow that client again to reclaim locks, without encountering
the edge conditions discussed in <xref target="server_failure" format="default"/>. the edge conditions discussed in <xref target="server_failure" format="default"/>.
</t> </t>
<t> <t>
Once a successful FREE_STATEID is done for a given stateid, any Once a successful FREE_STATEID is done for a given stateid, any
subsequent use of that stateid will result in an NFS4ERR_BAD_STATEID subsequent use of that stateid will result in an NFS4ERR_BAD_STATEID
error. error.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007-2008) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_GET_DIR_DELEGATION" numbered="true" toc="default"> <section anchor="OP_GET_DIR_DELEGATION" numbered="true" toc="default">
<name>Operation 46: GET_DIR_DELEGATION - Get a Directory Delegation</name> <name>Operation 46: GET_DIR_DELEGATION - Get a Directory Delegation</name>
<section toc="exclude" anchor="OP_GET_DIR_DELEGATION_ARGUMENT" numbered="true"> <section toc="exclude" anchor="OP_GET_DIR_DELEGATION_ARGUMENT" numbered="true">
<name>ARGUMENT</name> <name>ARGUMENT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
typedef nfstime4 attr_notice4; typedef nfstime4 attr_notice4;
struct GET_DIR_DELEGATION4args { struct GET_DIR_DELEGATION4args {
/* CURRENT_FH: delegated directory */ /* CURRENT_FH: delegated directory */
bool gdda_signal_deleg_avail; bool gdda_signal_deleg_avail;
bitmap4 gdda_notification_types; bitmap4 gdda_notification_types;
attr_notice4 gdda_child_attr_delay; attr_notice4 gdda_child_attr_delay;
attr_notice4 gdda_dir_attr_delay; attr_notice4 gdda_dir_attr_delay;
bitmap4 gdda_child_attributes; bitmap4 gdda_child_attributes;
bitmap4 gdda_dir_attributes; bitmap4 gdda_dir_attributes;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_GET_DIR_DELEGATION_RESULT" numbered="true"> <section toc="exclude" anchor="OP_GET_DIR_DELEGATION_RESULT" numbered="true">
<name>RESULT</name> <name>RESULT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct GET_DIR_DELEGATION4resok { struct GET_DIR_DELEGATION4resok {
verifier4 gddr_cookieverf; verifier4 gddr_cookieverf;
/* Stateid for get_dir_delegation */ /* Stateid for get_dir_delegation */
stateid4 gddr_stateid; stateid4 gddr_stateid;
/* Which notifications can the server support */ /* Which notifications can the server support */
bitmap4 gddr_notification; bitmap4 gddr_notification;
bitmap4 gddr_child_attributes; bitmap4 gddr_child_attributes;
bitmap4 gddr_dir_attributes; bitmap4 gddr_dir_attributes;
}; };
skipping to change at line 38156 skipping to change at line 37499
<t> <t>
The directory delegation covers all the entries in the The directory delegation covers all the entries in the
directory except the parent entry. That means if a directory and directory except the parent entry. That means if a directory and
its parent both hold directory delegations, any changes to the its parent both hold directory delegations, any changes to the
parent will not cause a notification to be sent for the child parent will not cause a notification to be sent for the child
even though the child's parent entry points to the parent even though the child's parent entry points to the parent
directory. directory.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007-2008) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_GETDEVICEINFO" numbered="true" toc="default"> <section anchor="OP_GETDEVICEINFO" numbered="true" toc="default">
<name>Operation 47: GETDEVICEINFO - Get Device Information</name> <name>Operation 47: GETDEVICEINFO - Get Device Information</name>
<section toc="exclude" anchor="OP_GETDEVICEINFO_ARGUMENT" numbered="true"> <section toc="exclude" anchor="OP_GETDEVICEINFO_ARGUMENT" numbered="true">
<name>ARGUMENT</name> <name>ARGUMENT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct GETDEVICEINFO4args { struct GETDEVICEINFO4args {
deviceid4 gdia_device_id; deviceid4 gdia_device_id;
layouttype4 gdia_layout_type; layouttype4 gdia_layout_type;
count4 gdia_maxcount; count4 gdia_maxcount;
bitmap4 gdia_notify_types; bitmap4 gdia_notify_types;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_GETDEVICEINFO_RESULT" numbered="true"> <section toc="exclude" anchor="OP_GETDEVICEINFO_RESULT" numbered="true">
<name>RESULT</name> <name>RESULT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct GETDEVICEINFO4resok { struct GETDEVICEINFO4resok {
device_addr4 gdir_device_addr; device_addr4 gdir_device_addr;
bitmap4 gdir_notification; bitmap4 gdir_notification;
}; };
union GETDEVICEINFO4res switch (nfsstat4 gdir_status) { union GETDEVICEINFO4res switch (nfsstat4 gdir_status) {
case NFS4_OK: case NFS4_OK:
GETDEVICEINFO4resok gdir_resok4; GETDEVICEINFO4resok gdir_resok4;
case NFS4ERR_TOOSMALL: case NFS4ERR_TOOSMALL:
count4 gdir_mincount; count4 gdir_mincount;
skipping to change at line 38338 skipping to change at line 37678
addressing mappings have changed. The client should assume addressing mappings have changed. The client should assume
that the results from the in-progress GETDEVICEINFO that the results from the in-progress GETDEVICEINFO
will be stale for the device ID will be stale for the device ID
once received, and so it should send another GETDEVICEINFO once received, and so it should send another GETDEVICEINFO
on the device ID. on the device ID.
</li> </li>
</ul> </ul>
</section> </section>
</section> </section>
<!--[auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007-2008) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_GETDEVICELIST" numbered="true" toc="default"> <section anchor="OP_GETDEVICELIST" numbered="true" toc="default">
<name>Operation 48: GETDEVICELIST - Get All Device Mappings for a File System</name> <name>Operation 48: GETDEVICELIST - Get All Device Mappings for a File System</name>
<section toc="exclude" anchor="OP_GETDEVICELIST_ARGUMENT" numbered="true"> <section toc="exclude" anchor="OP_GETDEVICELIST_ARGUMENT" numbered="true">
<name>ARGUMENT</name> <name>ARGUMENT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct GETDEVICELIST4args { struct GETDEVICELIST4args {
/* CURRENT_FH: object belonging to the file system */ /* CURRENT_FH: object belonging to the file system */
layouttype4 gdla_layout_type; layouttype4 gdla_layout_type;
/* number of deviceIDs to return */ /* number of deviceIDs to return */
count4 gdla_maxdevices; count4 gdla_maxdevices;
nfs_cookie4 gdla_cookie; nfs_cookie4 gdla_cookie;
verifier4 gdla_cookieverf; verifier4 gdla_cookieverf;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_GETDEVICELIST_RESULT" numbered="true"> <section toc="exclude" anchor="OP_GETDEVICELIST_RESULT" numbered="true">
<name>RESULT</name> <name>RESULT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct GETDEVICELIST4resok { struct GETDEVICELIST4resok {
nfs_cookie4 gdlr_cookie; nfs_cookie4 gdlr_cookie;
verifier4 gdlr_cookieverf; verifier4 gdlr_cookieverf;
deviceid4 gdlr_deviceid_list<>; deviceid4 gdlr_deviceid_list<>;
bool gdlr_eof; bool gdlr_eof;
}; };
union GETDEVICELIST4res switch (nfsstat4 gdlr_status) { union GETDEVICELIST4res switch (nfsstat4 gdlr_status) {
case NFS4_OK: case NFS4_OK:
GETDEVICELIST4resok gdlr_resok4; GETDEVICELIST4resok gdlr_resok4;
skipping to change at line 38420 skipping to change at line 37757
<t> <t>
An example of the use of this operation is for pNFS An example of the use of this operation is for pNFS
clients and servers that use LAYOUT4_BLOCK_VOLUME clients and servers that use LAYOUT4_BLOCK_VOLUME
layouts. In these environments it may be helpful layouts. In these environments it may be helpful
for a client to determine device accessibility upon for a client to determine device accessibility upon
first file system access. first file system access.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007-2008) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_LAYOUTCOMMIT" numbered="true" toc="default"> <section anchor="OP_LAYOUTCOMMIT" numbered="true" toc="default">
<name>Operation 49: LAYOUTCOMMIT - Commit Writes Made Using a Layout</name> <name>Operation 49: LAYOUTCOMMIT - Commit Writes Made Using a Layout</name>
<section toc="exclude" anchor="OP_LAYOUTCOMMIT_ARGUMENT" numbered="true"> <section toc="exclude" anchor="OP_LAYOUTCOMMIT_ARGUMENT" numbered="true">
<name>ARGUMENT</name> <name>ARGUMENT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
union newtime4 switch (bool nt_timechanged) { union newtime4 switch (bool nt_timechanged) {
case TRUE: case TRUE:
nfstime4 nt_time; nfstime4 nt_time;
case FALSE: case FALSE:
void; void;
}; };
union newoffset4 switch (bool no_newoffset) { union newoffset4 switch (bool no_newoffset) {
case TRUE: case TRUE:
offset4 no_offset; offset4 no_offset;
skipping to change at line 38455 skipping to change at line 37789
length4 loca_length; length4 loca_length;
bool loca_reclaim; bool loca_reclaim;
stateid4 loca_stateid; stateid4 loca_stateid;
newoffset4 loca_last_write_offset; newoffset4 loca_last_write_offset;
newtime4 loca_time_modify; newtime4 loca_time_modify;
layoutupdate4 loca_layoutupdate; layoutupdate4 loca_layoutupdate;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_LAYOUTCOMMIT_RESULT" numbered="true"> <section toc="exclude" anchor="OP_LAYOUTCOMMIT_RESULT" numbered="true">
<name>RESULT</name> <name>RESULT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
union newsize4 switch (bool ns_sizechanged) { union newsize4 switch (bool ns_sizechanged) {
case TRUE: case TRUE:
length4 ns_size; length4 ns_size;
case FALSE: case FALSE:
void; void;
}; };
struct LAYOUTCOMMIT4resok { struct LAYOUTCOMMIT4resok {
newsize4 locr_newsize; newsize4 locr_newsize;
}; };
skipping to change at line 38623 skipping to change at line 37957
they have successfully completed all their writes. Sending a they have successfully completed all their writes. Sending a
LAYOUTCOMMIT (if required) and then following with LAYOUTRETURN LAYOUTCOMMIT (if required) and then following with LAYOUTRETURN
can provide such an indication and allow for graceful and can provide such an indication and allow for graceful and
efficient recovery. efficient recovery.
</t> </t>
<t> <t>
If loca_reclaim is TRUE, the metadata server is free to If loca_reclaim is TRUE, the metadata server is free to
either examine or ignore the value in the field loca_stateid. either examine or ignore the value in the field loca_stateid.
The metadata server implementation might or might not The metadata server implementation might or might not
encode in its layout encode in its layout
stateid information that allows the metadate server to stateid information that allows the metadata server to
perform a consistency check on the LAYOUTCOMMIT request. perform a consistency check on the LAYOUTCOMMIT request.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007-2008) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_LAYOUTGET" numbered="true" toc="default"> <section anchor="OP_LAYOUTGET" numbered="true" toc="default">
<name>Operation 50: LAYOUTGET - Get Layout Information</name> <name>Operation 50: LAYOUTGET - Get Layout Information</name>
<section toc="exclude" anchor="OP_LAYOUTGET_ARGUMENT" numbered="true"> <section toc="exclude" anchor="OP_LAYOUTGET_ARGUMENT" numbered="true">
<name>ARGUMENT</name> <name>ARGUMENT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct LAYOUTGET4args { struct LAYOUTGET4args {
/* CURRENT_FH: file */ /* CURRENT_FH: file */
bool loga_signal_layout_avail; bool loga_signal_layout_avail;
layouttype4 loga_layout_type; layouttype4 loga_layout_type;
layoutiomode4 loga_iomode; layoutiomode4 loga_iomode;
offset4 loga_offset; offset4 loga_offset;
length4 loga_length; length4 loga_length;
length4 loga_minlength; length4 loga_minlength;
stateid4 loga_stateid; stateid4 loga_stateid;
count4 loga_maxcount; count4 loga_maxcount;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_LAYOUTGET_RESULT" numbered="true"> <section toc="exclude" anchor="OP_LAYOUTGET_RESULT" numbered="true">
<name>RESULT</name> <name>RESULT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct LAYOUTGET4resok { struct LAYOUTGET4resok {
bool logr_return_on_close; bool logr_return_on_close;
stateid4 logr_stateid; stateid4 logr_stateid;
layout4 logr_layout<>; layout4 logr_layout<>;
}; };
union LAYOUTGET4res switch (nfsstat4 logr_status) { union LAYOUTGET4res switch (nfsstat4 logr_status) {
case NFS4_OK: case NFS4_OK:
LAYOUTGET4resok logr_resok4; LAYOUTGET4resok logr_resok4;
case NFS4ERR_LAYOUTTRYLATER: case NFS4ERR_LAYOUTTRYLATER:
skipping to change at line 39332 skipping to change at line 38663
from GETDEVICEINFO are received before the client from GETDEVICEINFO are received before the client
gets results from LAYOUTGET, then there is no gets results from LAYOUTGET, then there is no
longer a race. If the results from LAYOUTGET are longer a race. If the results from LAYOUTGET are
received before the results from GETDEVICEINFO, the received before the results from GETDEVICEINFO, the
client can either wait for results of GETDEVICEINFO client can either wait for results of GETDEVICEINFO
or send another one to get possibly more up-to-date or send another one to get possibly more up-to-date
device address mappings for the device ID. device address mappings for the device ID.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007-2008) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_LAYOUTRETURN" numbered="true" toc="default"> <section anchor="OP_LAYOUTRETURN" numbered="true" toc="default">
<name>Operation 51: LAYOUTRETURN - Release Layout Information</name> <name>Operation 51: LAYOUTRETURN - Release Layout Information</name>
<section toc="exclude" anchor="OP_LAYOUTRETURN_ARGUMENT" numbered="true"> <section toc="exclude" anchor="OP_LAYOUTRETURN_ARGUMENT" numbered="true">
<name>ARGUMENT</name> <name>ARGUMENT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
/* Constants used for LAYOUTRETURN and CB_LAYOUTRECALL */ /* Constants used for LAYOUTRETURN and CB_LAYOUTRECALL */
const LAYOUT4_RET_REC_FILE = 1; const LAYOUT4_RET_REC_FILE = 1;
const LAYOUT4_RET_REC_FSID = 2; const LAYOUT4_RET_REC_FSID = 2;
const LAYOUT4_RET_REC_ALL = 3; const LAYOUT4_RET_REC_ALL = 3;
enum layoutreturn_type4 { enum layoutreturn_type4 {
LAYOUTRETURN4_FILE = LAYOUT4_RET_REC_FILE, LAYOUTRETURN4_FILE = LAYOUT4_RET_REC_FILE,
LAYOUTRETURN4_FSID = LAYOUT4_RET_REC_FSID, LAYOUTRETURN4_FSID = LAYOUT4_RET_REC_FSID,
LAYOUTRETURN4_ALL = LAYOUT4_RET_REC_ALL LAYOUTRETURN4_ALL = LAYOUT4_RET_REC_ALL
}; };
skipping to change at line 39376 skipping to change at line 38704
struct LAYOUTRETURN4args { struct LAYOUTRETURN4args {
/* CURRENT_FH: file */ /* CURRENT_FH: file */
bool lora_reclaim; bool lora_reclaim;
layouttype4 lora_layout_type; layouttype4 lora_layout_type;
layoutiomode4 lora_iomode; layoutiomode4 lora_iomode;
layoutreturn4 lora_layoutreturn; layoutreturn4 lora_layoutreturn;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_LAYOUTRETURN_RESULT" numbered="true"> <section toc="exclude" anchor="OP_LAYOUTRETURN_RESULT" numbered="true">
<name>RESULT</name> <name>RESULT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
union layoutreturn_stateid switch (bool lrs_present) { union layoutreturn_stateid switch (bool lrs_present) {
case TRUE: case TRUE:
stateid4 lrs_stateid; stateid4 lrs_stateid;
case FALSE: case FALSE:
void; void;
}; };
union LAYOUTRETURN4res switch (nfsstat4 lorr_status) { union LAYOUTRETURN4res switch (nfsstat4 lorr_status) {
case NFS4_OK: case NFS4_OK:
layoutreturn_stateid lorr_stateid; layoutreturn_stateid lorr_stateid;
skipping to change at line 39593 skipping to change at line 38921
LAYOUTRETURN4_FSID or LAYOUTRETURN4_ALL marks the end of the LAYOUTRETURN4_FSID or LAYOUTRETURN4_ALL marks the end of the
LAYOUTRETURN sequence. See <xref target="recall_robustness" format="default"/> LAYOUTRETURN sequence. See <xref target="recall_robustness" format="default"/>
for more details. for more details.
</t> </t>
<t> <t>
Once the client has returned all layouts referring to a particular Once the client has returned all layouts referring to a particular
device ID, the server <bcp14>MAY</bcp14> delete the device ID. device ID, the server <bcp14>MAY</bcp14> delete the device ID.
</t> </t>
</section> </section>
</section> </section>
<!--[auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007-2008) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_SECINFO_NO_NAME" numbered="true" toc="default"> <section anchor="OP_SECINFO_NO_NAME" numbered="true" toc="default">
<name>Operation 52: SECINFO_NO_NAME - Get Security on Unnamed Object</name> <name>Operation 52: SECINFO_NO_NAME - Get Security on Unnamed Object</name>
<section toc="exclude" anchor="OP_SECINFO_NO_NAME_ARGUMENT" numbered="true"> <section toc="exclude" anchor="OP_SECINFO_NO_NAME_ARGUMENT" numbered="true">
<name>ARGUMENT</name> <name>ARGUMENT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
enum secinfo_style4 { enum secinfo_style4 {
SECINFO_STYLE4_CURRENT_FH = 0, SECINFO_STYLE4_CURRENT_FH = 0,
SECINFO_STYLE4_PARENT = 1 SECINFO_STYLE4_PARENT = 1
}; };
/* CURRENT_FH: object or child directory */ /* CURRENT_FH: object or child directory */
typedef secinfo_style4 SECINFO_NO_NAME4args; typedef secinfo_style4 SECINFO_NO_NAME4args;
]]></sourcecode> ]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_SECINFO_NO_NAME_RESULT" numbered="true"> <section toc="exclude" anchor="OP_SECINFO_NO_NAME_RESULT" numbered="true">
<name>RESULT</name> <name>RESULT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
/* CURRENTFH: consumed if status is NFS4_OK */ /* CURRENTFH: consumed if status is NFS4_OK */
typedef SECINFO4res SECINFO_NO_NAME4res; typedef SECINFO4res SECINFO_NO_NAME4res;
]]></sourcecode> ]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_SECINFO_NO_NAME_DESCRIPTION" numbered="true"> <section toc="exclude" anchor="OP_SECINFO_NO_NAME_DESCRIPTION" numbered="true">
<name>DESCRIPTION</name> <name>DESCRIPTION</name>
<t> <t>
Like the SECINFO operation, SECINFO_NO_NAME is used by the Like the SECINFO operation, SECINFO_NO_NAME is used by the
client to obtain a list of valid RPC authentication flavors for client to obtain a list of valid RPC authentication flavors for
a specific file object. Unlike SECINFO, SECINFO_NO_NAME only a specific file object. Unlike SECINFO, SECINFO_NO_NAME only
skipping to change at line 39673 skipping to change at line 38998
See the discussion on SECINFO (<xref target="OP_SECINFO_DESCRIPTION" format="default"/>). See the discussion on SECINFO (<xref target="OP_SECINFO_DESCRIPTION" format="default"/>).
</t> </t>
</section> </section>
<section toc="exclude" anchor="OP_SECINFO_NO_NAME_IMPLEMENTATION" numbered="true"> <section toc="exclude" anchor="OP_SECINFO_NO_NAME_IMPLEMENTATION" numbered="true">
<name>IMPLEMENTATION</name> <name>IMPLEMENTATION</name>
<t> <t>
See the discussion on SECINFO (<xref target="OP_SECINFO_IMPLEMENTATION" format="default"/>). See the discussion on SECINFO (<xref target="OP_SECINFO_IMPLEMENTATION" format="default"/>).
</t> </t>
</section> </section>
</section> </section>
<!--[auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007-2008) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_SEQUENCE" numbered="true" toc="default"> <section anchor="OP_SEQUENCE" numbered="true" toc="default">
<name>Operation 53: SEQUENCE - Supply Per-Procedure Sequencing and Control</name> <name>Operation 53: SEQUENCE - Supply Per-Procedure Sequencing and Control</name>
<section toc="exclude" anchor="OP_SEQUENCE_ARGUMENT" numbered="true"> <section toc="exclude" anchor="OP_SEQUENCE_ARGUMENT" numbered="true">
<name>ARGUMENT</name> <name>ARGUMENT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct SEQUENCE4args { struct SEQUENCE4args {
sessionid4 sa_sessionid; sessionid4 sa_sessionid;
sequenceid4 sa_sequenceid; sequenceid4 sa_sequenceid;
slotid4 sa_slotid; slotid4 sa_slotid;
slotid4 sa_highest_slotid; slotid4 sa_highest_slotid;
bool sa_cachethis; bool sa_cachethis;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_SEQUENCE_RESULT" numbered="true"> <section toc="exclude" anchor="OP_SEQUENCE_RESULT" numbered="true">
<name>RESULT</name> <name>RESULT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
const SEQ4_STATUS_CB_PATH_DOWN = 0x00000001; const SEQ4_STATUS_CB_PATH_DOWN = 0x00000001;
const SEQ4_STATUS_CB_GSS_CONTEXTS_EXPIRING = 0x00000002; const SEQ4_STATUS_CB_GSS_CONTEXTS_EXPIRING = 0x00000002;
const SEQ4_STATUS_CB_GSS_CONTEXTS_EXPIRED = 0x00000004; const SEQ4_STATUS_CB_GSS_CONTEXTS_EXPIRED = 0x00000004;
const SEQ4_STATUS_EXPIRED_ALL_STATE_REVOKED = 0x00000008; const SEQ4_STATUS_EXPIRED_ALL_STATE_REVOKED = 0x00000008;
const SEQ4_STATUS_EXPIRED_SOME_STATE_REVOKED = 0x00000010; const SEQ4_STATUS_EXPIRED_SOME_STATE_REVOKED = 0x00000010;
const SEQ4_STATUS_ADMIN_STATE_REVOKED = 0x00000020; const SEQ4_STATUS_ADMIN_STATE_REVOKED = 0x00000020;
const SEQ4_STATUS_RECALLABLE_STATE_REVOKED = 0x00000040; const SEQ4_STATUS_RECALLABLE_STATE_REVOKED = 0x00000040;
const SEQ4_STATUS_LEASE_MOVED = 0x00000080; const SEQ4_STATUS_LEASE_MOVED = 0x00000080;
const SEQ4_STATUS_RESTART_RECLAIM_NEEDED = 0x00000100; const SEQ4_STATUS_RESTART_RECLAIM_NEEDED = 0x00000100;
const SEQ4_STATUS_CB_PATH_DOWN_SESSION = 0x00000200; const SEQ4_STATUS_CB_PATH_DOWN_SESSION = 0x00000200;
skipping to change at line 40057 skipping to change at line 39379
server restart, which logically happened after these server restart, which logically happened after these
operations, eliminated that state. In the operations, eliminated that state. In the
case of a partially executed COMPOUND, processing may reach case of a partially executed COMPOUND, processing may reach
an operation not processed during the earlier server instance, an operation not processed during the earlier server instance,
making this operation a new one and not performable on the making this operation a new one and not performable on the
existing session. In this case, NFS4ERR_DEADSESSION will be existing session. In this case, NFS4ERR_DEADSESSION will be
returned from that operation. returned from that operation.
</t> </t>
</section> </section>
</section> </section>
<!--[auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007-2008) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_SET_SSV" numbered="true" toc="default"> <section anchor="OP_SET_SSV" numbered="true" toc="default">
<name>Operation 54: SET_SSV - Update SSV for a Client ID</name> <name>Operation 54: SET_SSV - Update SSV for a Client ID</name>
<section toc="exclude" anchor="OP_SET_SSV_ARGUMENT" numbered="true"> <section toc="exclude" anchor="OP_SET_SSV_ARGUMENT" numbered="true">
<name>ARGUMENT</name> <name>ARGUMENT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct ssa_digest_input4 { struct ssa_digest_input4 {
SEQUENCE4args sdi_seqargs; SEQUENCE4args sdi_seqargs;
}; };
struct SET_SSV4args { struct SET_SSV4args {
opaque ssa_ssv<>; opaque ssa_ssv<>;
opaque ssa_digest<>; opaque ssa_digest<>;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_SET_SSV_RESULT" numbered="true"> <section toc="exclude" anchor="OP_SET_SSV_RESULT" numbered="true">
<name>RESULT</name> <name>RESULT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct ssr_digest_input4 { struct ssr_digest_input4 {
SEQUENCE4res sdi_seqres; SEQUENCE4res sdi_seqres;
}; };
struct SET_SSV4resok { struct SET_SSV4resok {
opaque ssr_digest<>; opaque ssr_digest<>;
}; };
union SET_SSV4res switch (nfsstat4 ssr_status) { union SET_SSV4res switch (nfsstat4 ssr_status) {
case NFS4_OK: case NFS4_OK:
skipping to change at line 40192 skipping to change at line 39511
However, if the client does send SET_SSV with SSV However, if the client does send SET_SSV with SSV
credentials, the digest protecting the arguments credentials, the digest protecting the arguments
uses the value of the SSV before ssa_ssv is XORed in, uses the value of the SSV before ssa_ssv is XORed in,
and the digest protecting the results uses the value and the digest protecting the results uses the value
of the SSV after the ssa_ssv is XORed in. of the SSV after the ssa_ssv is XORed in.
</t> </t>
</section> </section>
</section> </section>
<!--[auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_TEST_STATEID" numbered="true" toc="default"> <section anchor="OP_TEST_STATEID" numbered="true" toc="default">
<name>Operation 55: TEST_STATEID - Test Stateids for Validity</name> <name>Operation 55: TEST_STATEID - Test Stateids for Validity</name>
<section toc="exclude" anchor="OP_TEST_STATEID_ARGUMENT" numbered="true"> <section toc="exclude" anchor="OP_TEST_STATEID_ARGUMENT" numbered="true">
<name>ARGUMENT</name> <name>ARGUMENT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct TEST_STATEID4args { struct TEST_STATEID4args {
stateid4 ts_stateids<>; stateid4 ts_stateids<>;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_TEST_STATEID_RESULT" numbered="true"> <section toc="exclude" anchor="OP_TEST_STATEID_RESULT" numbered="true">
<name>RESULT</name> <name>RESULT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct TEST_STATEID4resok { struct TEST_STATEID4resok {
nfsstat4 tsr_status_codes<>; nfsstat4 tsr_status_codes<>;
}; };
union TEST_STATEID4res switch (nfsstat4 tsr_status) { union TEST_STATEID4res switch (nfsstat4 tsr_status) {
case NFS4_OK: case NFS4_OK:
TEST_STATEID4resok tsr_resok4; TEST_STATEID4resok tsr_resok4;
default: default:
void; void;
};]]></sourcecode> };]]></sourcecode>
skipping to change at line 40290 skipping to change at line 39606
</section> </section>
<section toc="exclude" anchor="OP_TEST_STATEID_IMPLEMENTATION" numbered="true"> <section toc="exclude" anchor="OP_TEST_STATEID_IMPLEMENTATION" numbered="true">
<name>IMPLEMENTATION</name> <name>IMPLEMENTATION</name>
<t> <t>
See Sections <xref target="stateid_structure" format="counter"/> and See Sections <xref target="stateid_structure" format="counter"/> and
<xref target="stateid_lifetime" format="counter"/> <xref target="stateid_lifetime" format="counter"/>
for a discussion of stateid structure, lifetime, and validation. for a discussion of stateid structure, lifetime, and validation.
</t> </t>
</section> </section>
</section> </section>
<!--[auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007-2008) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_WANT_DELEGATION" numbered="true" toc="default"> <section anchor="OP_WANT_DELEGATION" numbered="true" toc="default">
<name>Operation 56: WANT_DELEGATION - Request Delegation</name> <name>Operation 56: WANT_DELEGATION - Request Delegation</name>
<section toc="exclude" anchor="OP_WANT_DELEGATION_ARGUMENT" numbered="true"> <section toc="exclude" anchor="OP_WANT_DELEGATION_ARGUMENT" numbered="true">
<name>ARGUMENT</name> <name>ARGUMENT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
union deleg_claim4 switch (open_claim_type4 dc_claim) { union deleg_claim4 switch (open_claim_type4 dc_claim) {
/* /*
* No special rights to object. Ordinary delegation * No special rights to object. Ordinary delegation
* request of the specified object. Object identified * request of the specified object. Object identified
* by filehandle. * by filehandle.
*/ */
case CLAIM_FH: /* new to v4.1 */ case CLAIM_FH: /* new to v4.1 */
/* CURRENT_FH: object being delegated */ /* CURRENT_FH: object being delegated */
void; void;
skipping to change at line 40334 skipping to change at line 39647
open_delegation_type4 dc_delegate_type; open_delegation_type4 dc_delegate_type;
}; };
struct WANT_DELEGATION4args { struct WANT_DELEGATION4args {
uint32_t wda_want; uint32_t wda_want;
deleg_claim4 wda_claim; deleg_claim4 wda_claim;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_WANT_DELEGATION_RESULT" numbered="true"> <section toc="exclude" anchor="OP_WANT_DELEGATION_RESULT" numbered="true">
<name>RESULT</name> <name>RESULT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
union WANT_DELEGATION4res switch (nfsstat4 wdr_status) { union WANT_DELEGATION4res switch (nfsstat4 wdr_status) {
case NFS4_OK: case NFS4_OK:
open_delegation4 wdr_resok4; open_delegation4 wdr_resok4;
default: default:
void; void;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_WANT_DELEGATION_DESCRIPTION" numbered="true"> <section toc="exclude" anchor="OP_WANT_DELEGATION_DESCRIPTION" numbered="true">
<name>DESCRIPTION</name> <name>DESCRIPTION</name>
<t> <t>
skipping to change at line 40481 skipping to change at line 39794
<t> <t>
Servers will generally recall delegations assigned by WANT_DELEGATION Servers will generally recall delegations assigned by WANT_DELEGATION
on the same basis as those assigned by OPEN. CB_RECALL will generally on the same basis as those assigned by OPEN. CB_RECALL will generally
be done only when other clients perform operations inconsistent with be done only when other clients perform operations inconsistent with
the delegation. The normal response to aging of delegations is to use the delegation. The normal response to aging of delegations is to use
CB_RECALL_ANY, in order to give the client the opportunity to keep CB_RECALL_ANY, in order to give the client the opportunity to keep
the delegations most useful from its point of view. the delegations most useful from its point of view.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007-2008) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_DESTROY_CLIENTID" numbered="true" toc="default"> <section anchor="OP_DESTROY_CLIENTID" numbered="true" toc="default">
<name>Operation 57: DESTROY_CLIENTID - Destroy a Client ID</name> <name>Operation 57: DESTROY_CLIENTID - Destroy a Client ID</name>
<section toc="exclude" anchor="OP_DESTROY_CLIENTID_ARGUMENT" numbered="true"> <section toc="exclude" anchor="OP_DESTROY_CLIENTID_ARGUMENT" numbered="true">
<name>ARGUMENT</name> <name>ARGUMENT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct DESTROY_CLIENTID4args { struct DESTROY_CLIENTID4args {
clientid4 dca_clientid; clientid4 dca_clientid;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_DESTROY_CLIENTID_RESULT" numbered="true"> <section toc="exclude" anchor="OP_DESTROY_CLIENTID_RESULT" numbered="true">
<name>RESULT</name> <name>RESULT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct DESTROY_CLIENTID4res { struct DESTROY_CLIENTID4res {
nfsstat4 dcr_status; nfsstat4 dcr_status;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_DESTROY_CLIENTID_DESCRIPTION" numbered="true"> <section toc="exclude" anchor="OP_DESTROY_CLIENTID_DESCRIPTION" numbered="true">
<name>DESCRIPTION</name> <name>DESCRIPTION</name>
<t> <t>
The DESTROY_CLIENTID operation destroys the The DESTROY_CLIENTID operation destroys the
client ID. If there are sessions (both idle and client ID. If there are sessions (both idle and
non-idle), opens, locks, delegations, layouts, non-idle), opens, locks, delegations, layouts,
skipping to change at line 40541 skipping to change at line 39851
DESTROY_CLIENTID allows a server to immediately DESTROY_CLIENTID allows a server to immediately
reclaim the resources consumed by an unused client reclaim the resources consumed by an unused client
ID, and also to forget that it ever generated the ID, and also to forget that it ever generated the
client ID. By forgetting that it ever generated the client client ID. By forgetting that it ever generated the client
ID, the server can safely reuse the client ID on a ID, the server can safely reuse the client ID on a
future EXCHANGE_ID operation. future EXCHANGE_ID operation.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_RECLAIM_COMPLETE" numbered="true" toc="default"> <section anchor="OP_RECLAIM_COMPLETE" numbered="true" toc="default">
<name>Operation 58: RECLAIM_COMPLETE - Indicates Reclaims Finished</name> <name>Operation 58: RECLAIM_COMPLETE - Indicates Reclaims Finished</name>
<section toc="exclude" anchor="OP_RECLAIM_COMPLETE_ARGUMENT" numbered="true"> <section toc="exclude" anchor="OP_RECLAIM_COMPLETE_ARGUMENT" numbered="true">
<name>ARGUMENT</name> <name>ARGUMENT</name>
<!-- [rfced] The code in Sections 18.51.1 and 18.51.2 include "CODE BEGINS" <sourcecode type="xdr"><![CDATA[
tags, but they are not used elsewhere in the document. Please consider
whether any updates are needed.
18.51.1 (original):
<CODE BEGINS>
struct RECLAIM_COMPLETE4args {
/*
* If rca_one_fs TRUE,
*
* CURRENT_FH: object in
* file system reclaim is
* complete for.
*/
bool rca_one_fs;
};
<CODE ENDS>
18.51.2 (original):
<CODE BEGINS>
struct RECLAIM_COMPLETE4res {
nfsstat4 rcr_status;
};
<CODE ENDS>
<sourcecode type="" markers="true"><![CDATA[
struct RECLAIM_COMPLETE4args { struct RECLAIM_COMPLETE4args {
/* /*
* If rca_one_fs TRUE, * If rca_one_fs TRUE,
* *
* CURRENT_FH: object in * CURRENT_FH: object in
* file system reclaim is * file system reclaim is
* complete for. * complete for.
*/ */
bool rca_one_fs; bool rca_one_fs;
}; };
]]></sourcecode> ]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_RECLAIM_COMPLETE_RESULTS" numbered="true"> <section toc="exclude" anchor="OP_RECLAIM_COMPLETE_RESULTS" numbered="true">
<name>RESULTS</name> <name>RESULTS</name>
<sourcecode type="" markers="true"><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct RECLAIM_COMPLETE4res { struct RECLAIM_COMPLETE4res {
nfsstat4 rcr_status; nfsstat4 rcr_status;
}; };
]]></sourcecode> ]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_RECLAIM_COMPLETE_DESCRIPTION" numbered="true"> <section toc="exclude" anchor="OP_RECLAIM_COMPLETE_DESCRIPTION" numbered="true">
<name>DESCRIPTION</name> <name>DESCRIPTION</name>
<t> <t>
A RECLAIM_COMPLETE operation is used to indicate that the client A RECLAIM_COMPLETE operation is used to indicate that the client
has reclaimed all of the locking state that it will recover using has reclaimed all of the locking state that it will recover using
skipping to change at line 40772 skipping to change at line 40048
negative consequences of accepting it being limited, as in the negative consequences of accepting it being limited, as in the
case in which migration is not supported. However, if the server case in which migration is not supported. However, if the server
encounters a file system undergoing migration, the operation encounters a file system undergoing migration, the operation
cannot be accepted cannot be accepted
as if it were a global RECLAIM_COMPLETE without invalidating its as if it were a global RECLAIM_COMPLETE without invalidating its
intended use. intended use.
</li> </li>
</ul> </ul>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007-2008) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_ILLEGAL" numbered="true" toc="default"> <section anchor="OP_ILLEGAL" numbered="true" toc="default">
<name>Operation 10044: ILLEGAL - Illegal Operation</name> <name>Operation 10044: ILLEGAL - Illegal Operation</name>
<section toc="exclude" anchor="OP_ILLEGAL_ARGUMENTS" numbered="true"> <section toc="exclude" anchor="OP_ILLEGAL_ARGUMENTS" numbered="true">
<name>ARGUMENTS</name> <name>ARGUMENTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
void;]]></sourcecode> void;]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_ILLEGAL_RESULTS" numbered="true"> <section toc="exclude" anchor="OP_ILLEGAL_RESULTS" numbered="true">
<name>RESULTS</name> <name>RESULTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct ILLEGAL4res { struct ILLEGAL4res {
nfsstat4 status; nfsstat4 status;
};]]></sourcecode> };]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_ILLEGAL_DESCRIPTION" numbered="true"> <section toc="exclude" anchor="OP_ILLEGAL_DESCRIPTION" numbered="true">
<name>DESCRIPTION</name> <name>DESCRIPTION</name>
<t> <t>
This operation is a placeholder for encoding a result to handle the This operation is a placeholder for encoding a result to handle the
case of the client sending an operation code within COMPOUND that is case of the client sending an operation code within COMPOUND that is
not supported. See the COMPOUND procedure description for more not supported. See the COMPOUND procedure description for more
skipping to change at line 40813 skipping to change at line 40086
<t> <t>
A client will probably not send an operation with code OP_ILLEGAL but A client will probably not send an operation with code OP_ILLEGAL but
if it does, the response will be ILLEGAL4res just as it would be with if it does, the response will be ILLEGAL4res just as it would be with
any other invalid operation code. Note that if the server gets an any other invalid operation code. Note that if the server gets an
illegal operation code that is not OP_ILLEGAL, and if the server illegal operation code that is not OP_ILLEGAL, and if the server
checks for legal operation codes during the XDR decode phase, then the checks for legal operation codes during the XDR decode phase, then the
ILLEGAL4res would not be returned. ILLEGAL4res would not be returned.
</t> </t>
</section> </section>
</section> </section>
<!--[auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007) -->
<!-- Copyright (C) The Internet Society (2006) -->
</section> </section>
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="nfsv41callbackprocedures" numbered="true" toc="default"> <section anchor="nfsv41callbackprocedures" numbered="true" toc="default">
<name>NFSv4.1 Callback Procedures</name> <name>NFSv4.1 Callback Procedures</name>
<t> <t>
The procedures used for callbacks are defined in the following The procedures used for callbacks are defined in the following
sections. In the interest of clarity, the terms "client" and "server" sections. In the interest of clarity, the terms "client" and "server"
refer to NFS clients and servers, despite the fact that for an refer to NFS clients and servers, despite the fact that for an
individual callback RPC, the sense of these terms would be precisely individual callback RPC, the sense of these terms would be precisely
the opposite. the opposite.
</t> </t>
<t> <t>
Both procedures, CB_NULL and CB_COMPOUND, <bcp14>MUST</bcp14> be implemented. Both procedures, CB_NULL and CB_COMPOUND, <bcp14>MUST</bcp14> be implemented.
</t> </t>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007-2008) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="PROC_CB_NULL" numbered="true" toc="default"> <section anchor="PROC_CB_NULL" numbered="true" toc="default">
<name>Procedure 0: CB_NULL - No Operation</name> <name>Procedure 0: CB_NULL - No Operation</name>
<section toc="exclude" anchor="PROC_CB_NULL_ARGUMENTS" numbered="true"> <section toc="exclude" anchor="PROC_CB_NULL_ARGUMENTS" numbered="true">
<name>ARGUMENTS</name> <name>ARGUMENTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
void;]]></sourcecode> void;]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="PROC_CB_NULL_RESULTS" numbered="true"> <section toc="exclude" anchor="PROC_CB_NULL_RESULTS" numbered="true">
<name>RESULTS</name> <name>RESULTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
void;]]></sourcecode> void;]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="PROC_CB_NULL_DESCRIPTION" numbered="true"> <section toc="exclude" anchor="PROC_CB_NULL_DESCRIPTION" numbered="true">
<name>DESCRIPTION</name> <name>DESCRIPTION</name>
<t> <t>
CB_NULL is the standard ONC RPC NULL procedure, with the standard void argument and void response. Even though CB_NULL is the standard ONC RPC NULL procedure, with the standard void argument and void response. Even though
there is no direct functionality associated with this procedure, the there is no direct functionality associated with this procedure, the
server will use CB_NULL to confirm the existence of a path for RPCs server will use CB_NULL to confirm the existence of a path for RPCs
from the server to client. from the server to client.
</t> </t>
</section> </section>
<section toc="exclude" anchor="PROC_CB_NULL_ERRORS" numbered="true"> <section toc="exclude" anchor="PROC_CB_NULL_ERRORS" numbered="true">
<name>ERRORS</name> <name>ERRORS</name>
<t> <t>
None. None.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007-2008) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="PROC_CB_COMPOUND" numbered="true" toc="default"> <section anchor="PROC_CB_COMPOUND" numbered="true" toc="default">
<name>Procedure 1: CB_COMPOUND - Compound Operations</name> <name>Procedure 1: CB_COMPOUND - Compound Operations</name>
<section toc="exclude" anchor="PROC_CB_COMPOUND_ARGUMENTS" numbered="true"> <section toc="exclude" anchor="PROC_CB_COMPOUND_ARGUMENTS" numbered="true">
<name>ARGUMENTS</name> <name>ARGUMENTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
enum nfs_cb_opnum4 { enum nfs_cb_opnum4 {
OP_CB_GETATTR = 3, OP_CB_GETATTR = 3,
OP_CB_RECALL = 4, OP_CB_RECALL = 4,
/* Callback operations new to NFSv4.1 */ /* Callback operations new to NFSv4.1 */
OP_CB_LAYOUTRECALL = 5, OP_CB_LAYOUTRECALL = 5,
OP_CB_NOTIFY = 6, OP_CB_NOTIFY = 6,
OP_CB_PUSH_DELEG = 7, OP_CB_PUSH_DELEG = 7,
OP_CB_RECALL_ANY = 8, OP_CB_RECALL_ANY = 8,
OP_CB_RECALLABLE_OBJ_AVAIL = 9, OP_CB_RECALLABLE_OBJ_AVAIL = 9,
OP_CB_RECALL_SLOT = 10, OP_CB_RECALL_SLOT = 10,
skipping to change at line 40927 skipping to change at line 40188
struct CB_COMPOUND4args { struct CB_COMPOUND4args {
utf8str_cs tag; utf8str_cs tag;
uint32_t minorversion; uint32_t minorversion;
uint32_t callback_ident; uint32_t callback_ident;
nfs_cb_argop4 argarray<>; nfs_cb_argop4 argarray<>;
}; };
]]></sourcecode> ]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="PROC_CB_COMPOUND_RESULTS" numbered="true"> <section toc="exclude" anchor="PROC_CB_COMPOUND_RESULTS" numbered="true">
<name>RESULTS</name> <name>RESULTS</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
union nfs_cb_resop4 switch (unsigned resop) { union nfs_cb_resop4 switch (unsigned resop) {
case OP_CB_GETATTR: CB_GETATTR4res opcbgetattr; case OP_CB_GETATTR: CB_GETATTR4res opcbgetattr;
case OP_CB_RECALL: CB_RECALL4res opcbrecall; case OP_CB_RECALL: CB_RECALL4res opcbrecall;
/* new NFSv4.1 operations */ /* new NFSv4.1 operations */
case OP_CB_LAYOUTRECALL: case OP_CB_LAYOUTRECALL:
CB_LAYOUTRECALL4res CB_LAYOUTRECALL4res
opcblayoutrecall; opcblayoutrecall;
case OP_CB_NOTIFY: CB_NOTIFY4res opcbnotify; case OP_CB_NOTIFY: CB_NOTIFY4res opcbnotify;
skipping to change at line 41089 skipping to change at line 40350
<td align="left"> </td> <td align="left"> </td>
</tr> </tr>
<tr> <tr>
<td align="left">NFS4ERR_REQ_TOO_BIG</td> <td align="left">NFS4ERR_REQ_TOO_BIG</td>
<td align="left"> </td> <td align="left"> </td>
</tr> </tr>
</tbody> </tbody>
</table> </table>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007) -->
<!-- Copyright (C) The Internet Society (2006) -->
</section> </section>
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="nfsv41cboperations" numbered="true" toc="default"> <section anchor="nfsv41cboperations" numbered="true" toc="default">
<name>NFSv4.1 Callback Operations</name> <name>NFSv4.1 Callback Operations</name>
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_CB_GETATTR" numbered="true" toc="default"> <section anchor="OP_CB_GETATTR" numbered="true" toc="default">
<name>Operation 3: CB_GETATTR - Get Attributes</name> <name>Operation 3: CB_GETATTR - Get Attributes</name>
<section toc="exclude" anchor="OP_CB_GETATTR_ARGUMENT" numbered="true"> <section toc="exclude" anchor="OP_CB_GETATTR_ARGUMENT" numbered="true">
<name>ARGUMENT</name> <name>ARGUMENT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct CB_GETATTR4args { struct CB_GETATTR4args {
nfs_fh4 fh; nfs_fh4 fh;
bitmap4 attr_request; bitmap4 attr_request;
}; };
]]></sourcecode> ]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_CB_GETATTR_RESULT" numbered="true"> <section toc="exclude" anchor="OP_CB_GETATTR_RESULT" numbered="true">
<name>RESULT</name> <name>RESULT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct CB_GETATTR4resok { struct CB_GETATTR4resok {
fattr4 obj_attributes; fattr4 obj_attributes;
}; };
union CB_GETATTR4res switch (nfsstat4 status) { union CB_GETATTR4res switch (nfsstat4 status) {
case NFS4_OK: case NFS4_OK:
CB_GETATTR4resok resok4; CB_GETATTR4resok resok4;
default: default:
void; void;
}; };
skipping to change at line 41154 skipping to change at line 40406
</section> </section>
<section toc="exclude" anchor="OP_CB_GETATTR_IMPLEMENTATION" numbered="true"> <section toc="exclude" anchor="OP_CB_GETATTR_IMPLEMENTATION" numbered="true">
<name>IMPLEMENTATION</name> <name>IMPLEMENTATION</name>
<t> <t>
The client returns attrmask bits and the associated attribute The client returns attrmask bits and the associated attribute
values only for the change attribute, and attributes that it may values only for the change attribute, and attributes that it may
change (time_modify, and size). change (time_modify, and size).
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007-2008) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_CB_RECALL" numbered="true" toc="default"> <section anchor="OP_CB_RECALL" numbered="true" toc="default">
<name>Operation 4: CB_RECALL - Recall a Delegation</name> <name>Operation 4: CB_RECALL - Recall a Delegation</name>
<section toc="exclude" anchor="OP_CB_RECALL_ARGUMENT" numbered="true"> <section toc="exclude" anchor="OP_CB_RECALL_ARGUMENT" numbered="true">
<name>ARGUMENT</name> <name>ARGUMENT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct CB_RECALL4args { struct CB_RECALL4args {
stateid4 stateid; stateid4 stateid;
bool truncate; bool truncate;
nfs_fh4 fh; nfs_fh4 fh;
}; };
]]></sourcecode> ]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_CB_RECALL_RESULT" numbered="true"> <section toc="exclude" anchor="OP_CB_RECALL_RESULT" numbered="true">
<name>RESULT</name> <name>RESULT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct CB_RECALL4res { struct CB_RECALL4res {
nfsstat4 status; nfsstat4 status;
}; };
]]></sourcecode> ]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_CB_RECALL_DESCRIPTION" numbered="true"> <section toc="exclude" anchor="OP_CB_RECALL_DESCRIPTION" numbered="true">
<name>DESCRIPTION</name> <name>DESCRIPTION</name>
<t> <t>
The CB_RECALL operation is used to begin the process of recalling The CB_RECALL operation is used to begin the process of recalling
skipping to change at line 41215 skipping to change at line 40464
The client <bcp14>SHOULD</bcp14> reply to the callback immediately. The client <bcp14>SHOULD</bcp14> reply to the callback immediately.
Replying does not complete the recall except when Replying does not complete the recall except when
the value of the reply's status field is neither the value of the reply's status field is neither
NFS4ERR_DELAY nor NFS4_OK. The recall is not complete NFS4ERR_DELAY nor NFS4_OK. The recall is not complete
until the delegation is returned using a DELEGRETURN until the delegation is returned using a DELEGRETURN
operation. operation.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007-2008) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_CB_LAYOUTRECALL" numbered="true" toc="default"> <section anchor="OP_CB_LAYOUTRECALL" numbered="true" toc="default">
<name>Operation 5: CB_LAYOUTRECALL - Recall Layout from Client</name> <name>Operation 5: CB_LAYOUTRECALL - Recall Layout from Client</name>
<section toc="exclude" anchor="OP_CB_LAYOUTRECALL_ARGUMENT" numbered="true"> <section toc="exclude" anchor="OP_CB_LAYOUTRECALL_ARGUMENT" numbered="true">
<name>ARGUMENT</name> <name>ARGUMENT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
/* /*
* NFSv4.1 callback arguments and results * NFSv4.1 callback arguments and results
*/ */
enum layoutrecall_type4 { enum layoutrecall_type4 {
LAYOUTRECALL4_FILE = LAYOUT4_RET_REC_FILE, LAYOUTRECALL4_FILE = LAYOUT4_RET_REC_FILE,
LAYOUTRECALL4_FSID = LAYOUT4_RET_REC_FSID, LAYOUTRECALL4_FSID = LAYOUT4_RET_REC_FSID,
LAYOUTRECALL4_ALL = LAYOUT4_RET_REC_ALL LAYOUTRECALL4_ALL = LAYOUT4_RET_REC_ALL
}; };
skipping to change at line 41259 skipping to change at line 40505
struct CB_LAYOUTRECALL4args { struct CB_LAYOUTRECALL4args {
layouttype4 clora_type; layouttype4 clora_type;
layoutiomode4 clora_iomode; layoutiomode4 clora_iomode;
bool clora_changed; bool clora_changed;
layoutrecall4 clora_recall; layoutrecall4 clora_recall;
}; };
]]></sourcecode> ]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_CB_LAYOUTRECALL_RESULT" numbered="true"> <section toc="exclude" anchor="OP_CB_LAYOUTRECALL_RESULT" numbered="true">
<name>RESULT</name> <name>RESULT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct CB_LAYOUTRECALL4res { struct CB_LAYOUTRECALL4res {
nfsstat4 clorr_status; nfsstat4 clorr_status;
}; };
]]></sourcecode> ]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_CB_LAYOUTRECALL_DESCRIPTION" numbered="true"> <section toc="exclude" anchor="OP_CB_LAYOUTRECALL_DESCRIPTION" numbered="true">
<name>DESCRIPTION</name> <name>DESCRIPTION</name>
<t> <t>
The CB_LAYOUTRECALL operation is used by the server to recall The CB_LAYOUTRECALL operation is used by the server to recall
skipping to change at line 41284 skipping to change at line 40530
for one of the following: a specific layout of a specific file for one of the following: a specific layout of a specific file
(LAYOUTRECALL4_FILE), an entire file system ID (LAYOUTRECALL4_FILE), an entire file system ID
(LAYOUTRECALL4_FSID), or all file systems (LAYOUTRECALL4_ALL). (LAYOUTRECALL4_FSID), or all file systems (LAYOUTRECALL4_ALL).
</t> </t>
<t> <t>
The behavior of the operation varies based on the value of the The behavior of the operation varies based on the value of the
layoutrecall_type4. The value and behaviors are: layoutrecall_type4. The value and behaviors are:
</t> </t>
<dl newline="true" spacing="normal"> <dl newline="true" spacing="normal">
<dt>LAYOUTRECALL4_FILE</dt> <dt>LAYOUTRECALL4_FILE</dt>
<dd> <dd><t>
For a layout to match the recall request, the values of the following fields For a layout to match the recall request, the values of the following fields
must match those of the layout: clora_type, clora_iomode, must match those of the layout: clora_type, clora_iomode,
lor_fh, and the byte-range specified by lor_offset and lor_fh, and the byte-range specified by lor_offset and
lor_length. The clora_iomode field may have a special value lor_length. The clora_iomode field may have a special value
of LAYOUTIOMODE4_ANY. The special value LAYOUTIOMODE4_ANY will match any of LAYOUTIOMODE4_ANY. The special value LAYOUTIOMODE4_ANY will match any
iomode originally returned in a layout; therefore, it acts as a iomode originally returned in a layout; therefore, it acts as a
wild card. The other special value used is for wild card. The other special value used is for
lor_length. If lor_length has a value of NFS4_UINT64_MAX, the lor_length. If lor_length has a value of NFS4_UINT64_MAX, the
lor_length field means the maximum possible file size. If a lor_length field means the maximum possible file size. If a
matching layout is found, it <bcp14>MUST</bcp14> be returned using the matching layout is found, it <bcp14>MUST</bcp14> be returned using the
LAYOUTRETURN operation (see <xref target="OP_LAYOUTRETURN" format="default"/>). LAYOUTRETURN operation (see <xref target="OP_LAYOUTRETURN" format="default"/>).
An example of the field's special value use is if clora_iomode An example of the field's special value use is if clora_iomode
is LAYOUTIOMODE4_ANY, lor_offset is zero, and lor_length is is LAYOUTIOMODE4_ANY, lor_offset is zero, and lor_length is
NFS4_UINT64_MAX, then the entire layout is to be returned. NFS4_UINT64_MAX, then the entire layout is to be returned.</t>
</dd> <t>
<dt/>
<dd>
The NFS4ERR_NOMATCHING_LAYOUT error is only returned when the The NFS4ERR_NOMATCHING_LAYOUT error is only returned when the
client does not hold layouts for the file or if the client client does not hold layouts for the file or if the client
does not have any overlapping layouts for the specification in does not have any overlapping layouts for the specification in
the layout recall. the layout recall.</t>
</dd> </dd>
<dt>LAYOUTRECALL4_FSID and LAYOUTRECALL4_ALL</dt> <dt>LAYOUTRECALL4_FSID and LAYOUTRECALL4_ALL</dt>
<dd> <dd><t>
If LAYOUTRECALL4_FSID is specified, the fsid specifies the If LAYOUTRECALL4_FSID is specified, the fsid specifies the
file system for which any outstanding layouts <bcp14>MUST</bcp14> be file system for which any outstanding layouts <bcp14>MUST</bcp14> be
returned. If LAYOUTRECALL4_ALL is specified, all outstanding returned. If LAYOUTRECALL4_ALL is specified, all outstanding
layouts <bcp14>MUST</bcp14> be returned. In addition, LAYOUTRECALL4_FSID and layouts <bcp14>MUST</bcp14> be returned. In addition, LAYOUTRECALL4_FSID and
LAYOUTRECALL4_ALL specify that all the storage device ID to LAYOUTRECALL4_ALL specify that all the storage device ID to
storage device address mappings in the affected file system(s) storage device address mappings in the affected file system(s)
are also recalled. The respective LAYOUTRETURN with either are also recalled. The respective LAYOUTRETURN with either
LAYOUTRETURN4_FSID or LAYOUTRETURN4_ALL acknowledges to the LAYOUTRETURN4_FSID or LAYOUTRETURN4_ALL acknowledges to the
server that the client invalidated the said device mappings. server that the client invalidated the said device mappings.
See <xref target="bulk_layouts" format="default"/> for considerations with See <xref target="bulk_layouts" format="default"/> for considerations with
"bulk" recall of layouts. "bulk" recall of layouts.
</dd> </t>
<dt/> <t>
<dd>
The NFS4ERR_NOMATCHING_LAYOUT error is only returned when the The NFS4ERR_NOMATCHING_LAYOUT error is only returned when the
client does not hold layouts and does not have valid deviceid client does not hold layouts and does not have valid deviceid
mappings. mappings.</t>
</dd> </dd>
</dl> </dl>
<t> <t>
In processing the layout recall request, the client also varies In processing the layout recall request, the client also varies
its behavior based on the value of the clora_changed field. This its behavior based on the value of the clora_changed field. This
field is used by the server to provide additional context for field is used by the server to provide additional context for
the reason why the layout is being recalled. A FALSE value for the reason why the layout is being recalled. A FALSE value for
clora_changed indicates that no change in the layout is expected clora_changed indicates that no change in the layout is expected
and the client may write modified data to the storage devices and the client may write modified data to the storage devices
involved; this must be done prior to returning the layout via involved; this must be done prior to returning the layout via
skipping to change at line 41410 skipping to change at line 40653
<t> <t>
If a server needs to delete a device ID and there are layouts If a server needs to delete a device ID and there are layouts
referring to the device ID, CB_LAYOUTRECALL <bcp14>MUST</bcp14> be invoked to referring to the device ID, CB_LAYOUTRECALL <bcp14>MUST</bcp14> be invoked to
cause the client to return all layouts referring to the device ID cause the client to return all layouts referring to the device ID
before the server can delete the device ID. If the client before the server can delete the device ID. If the client
does not return the affected layouts, the server <bcp14>MAY</bcp14> revoke does not return the affected layouts, the server <bcp14>MAY</bcp14> revoke
the layouts. the layouts.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007-2008) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_CB_NOTIFY" numbered="true" toc="default"> <section anchor="OP_CB_NOTIFY" numbered="true" toc="default">
<name>Operation 6: CB_NOTIFY - Notify Client of Directory Changes</name> <name>Operation 6: CB_NOTIFY - Notify Client of Directory Changes</name>
<section toc="exclude" anchor="OP_CB_NOTIFY_ARGUMENT" numbered="true"> <section toc="exclude" anchor="OP_CB_NOTIFY_ARGUMENT" numbered="true">
<name>ARGUMENT</name> <name>ARGUMENT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
/* /*
* Directory notification types. * Directory notification types.
*/ */
enum notify_type4 { enum notify_type4 {
NOTIFY4_CHANGE_CHILD_ATTRS = 0, NOTIFY4_CHANGE_CHILD_ATTRS = 0,
NOTIFY4_CHANGE_DIR_ATTRS = 1, NOTIFY4_CHANGE_DIR_ATTRS = 1,
NOTIFY4_REMOVE_ENTRY = 2, NOTIFY4_REMOVE_ENTRY = 2,
NOTIFY4_ADD_ENTRY = 3, NOTIFY4_ADD_ENTRY = 3,
NOTIFY4_RENAME_ENTRY = 4, NOTIFY4_RENAME_ENTRY = 4,
NOTIFY4_CHANGE_COOKIE_VERIFIER = 5 NOTIFY4_CHANGE_COOKIE_VERIFIER = 5
skipping to change at line 41497 skipping to change at line 40737
struct CB_NOTIFY4args { struct CB_NOTIFY4args {
stateid4 cna_stateid; stateid4 cna_stateid;
nfs_fh4 cna_fh; nfs_fh4 cna_fh;
notify4 cna_changes<>; notify4 cna_changes<>;
}; };
]]></sourcecode> ]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_CB_NOTIFY_RESULT" numbered="true"> <section toc="exclude" anchor="OP_CB_NOTIFY_RESULT" numbered="true">
<name>RESULT</name> <name>RESULT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct CB_NOTIFY4res { struct CB_NOTIFY4res {
nfsstat4 cnr_status; nfsstat4 cnr_status;
}; };
]]></sourcecode> ]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_CB_NOTIFY_DESCRIPTION" numbered="true"> <section toc="exclude" anchor="OP_CB_NOTIFY_DESCRIPTION" numbered="true">
<name>DESCRIPTION</name> <name>DESCRIPTION</name>
<t> <t>
The CB_NOTIFY operation is used by the server to The CB_NOTIFY operation is used by the server to
skipping to change at line 41629 skipping to change at line 40869
<dd> <dd>
If the cookie verifier changes while If the cookie verifier changes while
a client is holding a delegation, the server will notify the a client is holding a delegation, the server will notify the
client so that it can invalidate its cookies and re-send a client so that it can invalidate its cookies and re-send a
READDIR to get the new set of cookies. READDIR to get the new set of cookies.
</dd> </dd>
</dl> </dl>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007-2008) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_CB_PUSH_DELEG" numbered="true" toc="default"> <section anchor="OP_CB_PUSH_DELEG" numbered="true" toc="default">
<name>Operation 7: CB_PUSH_DELEG - Offer Previously Requested Delegation to Client</name> <name>Operation 7: CB_PUSH_DELEG - Offer Previously Requested Delegation to Client</name>
<section toc="exclude" anchor="OP_CB_PUSH_DELEG_ARGUMENT" numbered="true"> <section toc="exclude" anchor="OP_CB_PUSH_DELEG_ARGUMENT" numbered="true">
<name>ARGUMENT</name> <name>ARGUMENT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct CB_PUSH_DELEG4args { struct CB_PUSH_DELEG4args {
nfs_fh4 cpda_fh; nfs_fh4 cpda_fh;
open_delegation4 cpda_delegation; open_delegation4 cpda_delegation;
}; };
]]></sourcecode> ]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_CB_PUSH_DELEG_RESULT" numbered="true"> <section toc="exclude" anchor="OP_CB_PUSH_DELEG_RESULT" numbered="true">
<name>RESULT</name> <name>RESULT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct CB_PUSH_DELEG4res { struct CB_PUSH_DELEG4res {
nfsstat4 cpdr_status; nfsstat4 cpdr_status;
}; };
]]></sourcecode> ]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_CB_PUSH_DELEG_DESCRIPTION" numbered="true"> <section toc="exclude" anchor="OP_CB_PUSH_DELEG_DESCRIPTION" numbered="true">
<name>DESCRIPTION</name> <name>DESCRIPTION</name>
<t> <t>
CB_PUSH_DELEG is used by the server both to signal to the CB_PUSH_DELEG is used by the server both to signal to the
skipping to change at line 41690 skipping to change at line 40927
<bcp14>MAY</bcp14> be processed behind other delegation requests or registered <bcp14>MAY</bcp14> be processed behind other delegation requests or registered
wants. wants.
</t> </t>
<t> <t>
When a client returns a status other than NFS4_OK, NFS4ERR_DELAY, When a client returns a status other than NFS4_OK, NFS4ERR_DELAY,
or NFS4ERR_REJECT_DELAY, the want remains pending, although or NFS4ERR_REJECT_DELAY, the want remains pending, although
servers may decide to cancel the want by sending a CB_WANTS_CANCELLED. servers may decide to cancel the want by sending a CB_WANTS_CANCELLED.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007-2008) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_CB_RECALL_ANY" numbered="true" toc="default"> <section anchor="OP_CB_RECALL_ANY" numbered="true" toc="default">
<name>Operation 8: CB_RECALL_ANY - Keep Any N Recallable Objects</name> <name>Operation 8: CB_RECALL_ANY - Keep Any N Recallable Objects</name>
<section toc="exclude" anchor="OP_CB_RECALL_ANY_ARGUMENT" numbered="true"> <section toc="exclude" anchor="OP_CB_RECALL_ANY_ARGUMENT" numbered="true">
<name>ARGUMENT</name> <name>ARGUMENT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
const RCA4_TYPE_MASK_RDATA_DLG = 0; const RCA4_TYPE_MASK_RDATA_DLG = 0;
const RCA4_TYPE_MASK_WDATA_DLG = 1; const RCA4_TYPE_MASK_WDATA_DLG = 1;
const RCA4_TYPE_MASK_DIR_DLG = 2; const RCA4_TYPE_MASK_DIR_DLG = 2;
const RCA4_TYPE_MASK_FILE_LAYOUT = 3; const RCA4_TYPE_MASK_FILE_LAYOUT = 3;
const RCA4_TYPE_MASK_BLK_LAYOUT = 4; const RCA4_TYPE_MASK_BLK_LAYOUT = 4;
const RCA4_TYPE_MASK_OBJ_LAYOUT_MIN = 8; const RCA4_TYPE_MASK_OBJ_LAYOUT_MIN = 8;
const RCA4_TYPE_MASK_OBJ_LAYOUT_MAX = 9; const RCA4_TYPE_MASK_OBJ_LAYOUT_MAX = 9;
const RCA4_TYPE_MASK_OTHER_LAYOUT_MIN = 12; const RCA4_TYPE_MASK_OTHER_LAYOUT_MIN = 12;
const RCA4_TYPE_MASK_OTHER_LAYOUT_MAX = 15; const RCA4_TYPE_MASK_OTHER_LAYOUT_MAX = 15;
struct CB_RECALL_ANY4args { struct CB_RECALL_ANY4args {
uint32_t craa_objects_to_keep; uint32_t craa_objects_to_keep;
bitmap4 craa_type_mask; bitmap4 craa_type_mask;
}; };
]]></sourcecode> ]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_CB_RECALL_ANY_RESULT" numbered="true"> <section toc="exclude" anchor="OP_CB_RECALL_ANY_RESULT" numbered="true">
<name>RESULT</name> <name>RESULT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct CB_RECALL_ANY4res { struct CB_RECALL_ANY4res {
nfsstat4 crar_status; nfsstat4 crar_status;
}; };
]]></sourcecode> ]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_CB_RECALL_ANY_DESCRIPTION" numbered="true"> <section toc="exclude" anchor="OP_CB_RECALL_ANY_DESCRIPTION" numbered="true">
<name>DESCRIPTION</name> <name>DESCRIPTION</name>
<t> <t>
The server may decide that it cannot hold all of the state for The server may decide that it cannot hold all of the state for
skipping to change at line 41896 skipping to change at line 41130
it sends. Should the client fail to return requested objects, it is it sends. Should the client fail to return requested objects, it is
up to the server to handle this situation, typically by sending up to the server to handle this situation, typically by sending
specific recalls (i.e., sending CB_RECALL operations) specific recalls (i.e., sending CB_RECALL operations)
to properly limit resource usage. The server to properly limit resource usage. The server
should give the client enough time to return objects before should give the client enough time to return objects before
proceeding to specific recalls. This time should not be less proceeding to specific recalls. This time should not be less
than the lease period. than the lease period.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007-2008) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_CB_RECALLABLE_OBJ_AVAIL" numbered="true" toc="default"> <section anchor="OP_CB_RECALLABLE_OBJ_AVAIL" numbered="true" toc="default">
<name>Operation 9: CB_RECALLABLE_OBJ_AVAIL - Signal Resources for Recallable Objects</name> <name>Operation 9: CB_RECALLABLE_OBJ_AVAIL - Signal Resources for Recallable Objects</name>
<section toc="exclude" anchor="OP_CB_RECALLABLE_OBJ_AVAIL_ARGUMENT" numbered="true"> <section toc="exclude" anchor="OP_CB_RECALLABLE_OBJ_AVAIL_ARGUMENT" numbered="true">
<name>ARGUMENT</name> <name>ARGUMENT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
typedef CB_RECALL_ANY4args CB_RECALLABLE_OBJ_AVAIL4args; typedef CB_RECALL_ANY4args CB_RECALLABLE_OBJ_AVAIL4args;
]]></sourcecode> ]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_CB_RECALLABLE_OBJ_AVAIL_RESULT" numbered="true"> <section toc="exclude" anchor="OP_CB_RECALLABLE_OBJ_AVAIL_RESULT" numbered="true">
<name>RESULT</name> <name>RESULT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct CB_RECALLABLE_OBJ_AVAIL4res { struct CB_RECALLABLE_OBJ_AVAIL4res {
nfsstat4 croa_status; nfsstat4 croa_status;
}; };
]]></sourcecode> ]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_CB_RECALLABLE_OBJ_AVAIL_DESCRIPTION" numbered="true"> <section toc="exclude" anchor="OP_CB_RECALLABLE_OBJ_AVAIL_DESCRIPTION" numbered="true">
<name>DESCRIPTION</name> <name>DESCRIPTION</name>
<t> <t>
CB_RECALLABLE_OBJ_AVAIL is used by the server to signal the CB_RECALLABLE_OBJ_AVAIL is used by the server to signal the
client that the server has resources to grant recallable client that the server has resources to grant recallable
skipping to change at line 41953 skipping to change at line 41184
or reduce any reservation it is maintaining on behalf or reduce any reservation it is maintaining on behalf
of the client. of the client.
Thus, if the client desires to acquire more Thus, if the client desires to acquire more
recallable objects, it needs to reply quickly recallable objects, it needs to reply quickly
to CB_RECALLABLE_OBJ_AVAIL, and then send the to CB_RECALLABLE_OBJ_AVAIL, and then send the
appropriate operations to acquire recallable appropriate operations to acquire recallable
objects. objects.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007-2008) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_CB_RECALL_SLOT" numbered="true" toc="default"> <section anchor="OP_CB_RECALL_SLOT" numbered="true" toc="default">
<name>Operation 10: CB_RECALL_SLOT - Change Flow Control Limits</name> <name>Operation 10: CB_RECALL_SLOT - Change Flow Control Limits</name>
<section toc="exclude" anchor="OP_CB_RECALL_SLOT_ARGUMENT" numbered="true"> <section toc="exclude" anchor="OP_CB_RECALL_SLOT_ARGUMENT" numbered="true">
<name>ARGUMENT</name> <name>ARGUMENT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct CB_RECALL_SLOT4args { struct CB_RECALL_SLOT4args {
slotid4 rsa_target_highest_slotid; slotid4 rsa_target_highest_slotid;
}; };
]]></sourcecode> ]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_CB_RECALL_SLOT_RESULT" numbered="true"> <section toc="exclude" anchor="OP_CB_RECALL_SLOT_RESULT" numbered="true">
<name>RESULT</name> <name>RESULT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct CB_RECALL_SLOT4res { struct CB_RECALL_SLOT4res {
nfsstat4 rsr_status; nfsstat4 rsr_status;
}; };
]]></sourcecode> ]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_CB_RECALL_SLOT_DESCRIPTION" numbered="true"> <section toc="exclude" anchor="OP_CB_RECALL_SLOT_DESCRIPTION" numbered="true">
<name>DESCRIPTION</name> <name>DESCRIPTION</name>
<t> <t>
The CB_RECALL_SLOT operation requests the client to The CB_RECALL_SLOT operation requests the client to
return session slots, and if applicable, transport return session slots, and if applicable, transport
skipping to change at line 41996 skipping to change at line 41224
<t> <t>
If the session has only non-RDMA connections associated with its If the session has only non-RDMA connections associated with its
operations channel, then the client need only wait operations channel, then the client need only wait
for all outstanding requests with a slot ID &gt; for all outstanding requests with a slot ID &gt;
rsa_target_highest_slotid to complete, then send rsa_target_highest_slotid to complete, then send
a single COMPOUND consisting of a single SEQUENCE operation, a single COMPOUND consisting of a single SEQUENCE operation,
with the sa_highestslot field set to rsa_target_highest_slotid. with the sa_highestslot field set to rsa_target_highest_slotid.
If there are RDMA-based connections associated with If there are RDMA-based connections associated with
operation channel, then the client needs to also operation channel, then the client needs to also
send enough zero-length "RDMA Send" messages to take the total send enough zero-length "RDMA Send" messages to take the total
<!-- [auth] Please leave this use of "Send" capitalized in order to denote
an artifact particular to RDMA-based communication. Thanks. -->
RDMA credit count to rsa_target_highest_slotid + 1 or below. RDMA credit count to rsa_target_highest_slotid + 1 or below.
</t> </t>
</section> </section>
<section toc="exclude" anchor="OP_CB_RECALL_SLOT_IMPLEMENTATION" numbered="true"> <section toc="exclude" anchor="OP_CB_RECALL_SLOT_IMPLEMENTATION" numbered="true">
<name>IMPLEMENTATION</name> <name>IMPLEMENTATION</name>
<t> <t>
If the client fails to reduce highest slot it has on the fore channel If the client fails to reduce highest slot it has on the fore channel
to what the server requests, the server can force the issue to what the server requests, the server can force the issue
by asserting flow control on the receive side of by asserting flow control on the receive side of
all connections bound to the fore channel, and then all connections bound to the fore channel, and then
finish servicing all outstanding requests that are finish servicing all outstanding requests that are
in slots greater than rsa_target_highest_slotid. Once that in slots greater than rsa_target_highest_slotid. Once that
is done, the server can then open the flow control, and any time is done, the server can then open the flow control, and any time
the client sends a new request on a slot greater than the client sends a new request on a slot greater than
rsa_target_highest_slotid, the server can return NFS4ERR_BADSLOT. rsa_target_highest_slotid, the server can return NFS4ERR_BADSLOT.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007-2008) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_CB_SEQUENCE" numbered="true" toc="default"> <section anchor="OP_CB_SEQUENCE" numbered="true" toc="default">
<name>Operation 11: CB_SEQUENCE - Supply Backchannel Sequencing and Control</name> <name>Operation 11: CB_SEQUENCE - Supply Backchannel Sequencing and Control</name>
<section toc="exclude" anchor="OP_CB_SEQUENCE_ARGUMENT" numbered="true"> <section toc="exclude" anchor="OP_CB_SEQUENCE_ARGUMENT" numbered="true">
<name>ARGUMENT</name> <name>ARGUMENT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct referring_call4 { struct referring_call4 {
sequenceid4 rc_sequenceid; sequenceid4 rc_sequenceid;
slotid4 rc_slotid; slotid4 rc_slotid;
}; };
struct referring_call_list4 { struct referring_call_list4 {
sessionid4 rcl_sessionid; sessionid4 rcl_sessionid;
referring_call4 rcl_referring_calls<>; referring_call4 rcl_referring_calls<>;
}; };
skipping to change at line 42046 skipping to change at line 41269
sequenceid4 csa_sequenceid; sequenceid4 csa_sequenceid;
slotid4 csa_slotid; slotid4 csa_slotid;
slotid4 csa_highest_slotid; slotid4 csa_highest_slotid;
bool csa_cachethis; bool csa_cachethis;
referring_call_list4 csa_referring_call_lists<>; referring_call_list4 csa_referring_call_lists<>;
}; };
]]></sourcecode> ]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_CB_SEQUENCE_RESULT" numbered="true"> <section toc="exclude" anchor="OP_CB_SEQUENCE_RESULT" numbered="true">
<name>RESULT</name> <name>RESULT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct CB_SEQUENCE4resok { struct CB_SEQUENCE4resok {
sessionid4 csr_sessionid; sessionid4 csr_sessionid;
sequenceid4 csr_sequenceid; sequenceid4 csr_sequenceid;
slotid4 csr_slotid; slotid4 csr_slotid;
slotid4 csr_highest_slotid; slotid4 csr_highest_slotid;
slotid4 csr_target_highest_slotid; slotid4 csr_target_highest_slotid;
}; };
union CB_SEQUENCE4res switch (nfsstat4 csr_status) { union CB_SEQUENCE4res switch (nfsstat4 csr_status) {
case NFS4_OK: case NFS4_OK:
skipping to change at line 42158 skipping to change at line 41381
csr_highest_slotid and csr_target_highest_slotid. The csr_highest_slotid and csr_target_highest_slotid. The
former is the highest slot ID the client will accept former is the highest slot ID the client will accept
in a future CB_SEQUENCE operation, and <bcp14>SHOULD NOT</bcp14> be in a future CB_SEQUENCE operation, and <bcp14>SHOULD NOT</bcp14> be
less than the value of csa_highest_slotid (but see less than the value of csa_highest_slotid (but see
<xref target="Slot_Identifiers_and_Server_Reply_Cache" format="default"/> for an exception). The latter is the highest slot <xref target="Slot_Identifiers_and_Server_Reply_Cache" format="default"/> for an exception). The latter is the highest slot
ID the client would prefer the server use on a future ID the client would prefer the server use on a future
CB_SEQUENCE operation. CB_SEQUENCE operation.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007-2008) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_CB_WANTS_CANCELLED" numbered="true" toc="default"> <section anchor="OP_CB_WANTS_CANCELLED" numbered="true" toc="default">
<name>Operation 12: CB_WANTS_CANCELLED - Cancel Pending Delegation Wants</name> <name>Operation 12: CB_WANTS_CANCELLED - Cancel Pending Delegation Wants</name>
<section toc="exclude" anchor="OP_CB_WANTS_CANCELLED_ARGUMENT" numbered="true"> <section toc="exclude" anchor="OP_CB_WANTS_CANCELLED_ARGUMENT" numbered="true">
<name>ARGUMENT</name> <name>ARGUMENT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct CB_WANTS_CANCELLED4args { struct CB_WANTS_CANCELLED4args {
bool cwca_contended_wants_cancelled; bool cwca_contended_wants_cancelled;
bool cwca_resourced_wants_cancelled; bool cwca_resourced_wants_cancelled;
}; };
]]></sourcecode> ]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_CB_WANTS_CANCELLED_RESULT" numbered="true"> <section toc="exclude" anchor="OP_CB_WANTS_CANCELLED_RESULT" numbered="true">
<name>RESULT</name> <name>RESULT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct CB_WANTS_CANCELLED4res { struct CB_WANTS_CANCELLED4res {
nfsstat4 cwcr_status; nfsstat4 cwcr_status;
}; };
]]></sourcecode> ]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_CB_WANTS_CANCELLED_DESCRIPTION" numbered="true"> <section toc="exclude" anchor="OP_CB_WANTS_CANCELLED_DESCRIPTION" numbered="true">
<name>DESCRIPTION</name> <name>DESCRIPTION</name>
<t> <t>
The CB_WANTS_CANCELLED operation is used to notify the client that The CB_WANTS_CANCELLED operation is used to notify the client that
some or all of the wants it registered for recallable delegations and layouts some or all of the wants it registered for recallable delegations and layouts
skipping to change at line 42216 skipping to change at line 41436
When a client has an OPEN, WANT_DELEGATION, or GET_DIR_DELEGATION request When a client has an OPEN, WANT_DELEGATION, or GET_DIR_DELEGATION request
outstanding, when a CB_WANTS_CANCELLED is sent, the server may need to outstanding, when a CB_WANTS_CANCELLED is sent, the server may need to
make clear to the client whether a promise to signal delegation availability make clear to the client whether a promise to signal delegation availability
happened before the CB_WANTS_CANCELLED and is thus covered by it, or after happened before the CB_WANTS_CANCELLED and is thus covered by it, or after
the CB_WANTS_CANCELLED in which case it was not covered by it. The server the CB_WANTS_CANCELLED in which case it was not covered by it. The server
can make this distinction by putting the appropriate requests into the can make this distinction by putting the appropriate requests into the
list of referring calls in the associated CB_SEQUENCE. list of referring calls in the associated CB_SEQUENCE.
</t> </t>
</section> </section>
</section> </section>
<!--[auth] Copyright (C) The Internet Society (2006) -->
<!-- Copyright (C) The IETF Trust (2007-2008) -->
<section anchor="OP_CB_NOTIFY_LOCK" numbered="true" toc="default"> <section anchor="OP_CB_NOTIFY_LOCK" numbered="true" toc="default">
<name>Operation 13: CB_NOTIFY_LOCK - Notify Client of Possible Lock Availability</name> <name>Operation 13: CB_NOTIFY_LOCK - Notify Client of Possible Lock Availability</name>
<section toc="exclude" anchor="OP_CB_NOTIFY_LOCK_ARGUMENT" numbered="true"> <section toc="exclude" anchor="OP_CB_NOTIFY_LOCK_ARGUMENT" numbered="true">
<name>ARGUMENT</name> <name>ARGUMENT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct CB_NOTIFY_LOCK4args { struct CB_NOTIFY_LOCK4args {
nfs_fh4 cnla_fh; nfs_fh4 cnla_fh;
lock_owner4 cnla_lock_owner; lock_owner4 cnla_lock_owner;
}; };
]]></sourcecode> ]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_CB_NOTIFY_LOCK_RESULT" numbered="true"> <section toc="exclude" anchor="OP_CB_NOTIFY_LOCK_RESULT" numbered="true">
<name>RESULT</name> <name>RESULT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct CB_NOTIFY_LOCK4res { struct CB_NOTIFY_LOCK4res {
nfsstat4 cnlr_status; nfsstat4 cnlr_status;
}; };
]]></sourcecode> ]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_CB_NOTIFY_LOCK_DESCRIPTION" numbered="true"> <section toc="exclude" anchor="OP_CB_NOTIFY_LOCK_DESCRIPTION" numbered="true">
<name>DESCRIPTION</name> <name>DESCRIPTION</name>
<t> <t>
The server can use this operation to indicate that a byte-range lock for the given The server can use this operation to indicate that a byte-range lock for the given
file and lock-owner, previously requested by the client via an unsuccessful file and lock-owner, previously requested by the client via an unsuccessful
skipping to change at line 42286 skipping to change at line 41504
client must still rely on polling for blocking locks, as described in client must still rely on polling for blocking locks, as described in
<xref target="blocking_locks" format="default"/>. <xref target="blocking_locks" format="default"/>.
</t> </t>
<t> <t>
Similarly, the client is not required to implement this callback, and even Similarly, the client is not required to implement this callback, and even
it does, is still free to ignore it. Therefore, the server <bcp14>MUST NOT</bcp14> assume it does, is still free to ignore it. Therefore, the server <bcp14>MUST NOT</bcp14> assume
that the client will act based on the callback. that the client will act based on the callback.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007-2008) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_CB_NOTIFY_DEVICEID" numbered="true" toc="default"> <section anchor="OP_CB_NOTIFY_DEVICEID" numbered="true" toc="default">
<name>Operation 14: CB_NOTIFY_DEVICEID - Notify Client of Device ID Changes</name> <name>Operation 14: CB_NOTIFY_DEVICEID - Notify Client of Device ID Changes</name>
<section toc="exclude" anchor="OP_CB_NOTIFY_DEVICEID_ARGUMENT" numbered="true"> <section toc="exclude" anchor="OP_CB_NOTIFY_DEVICEID_ARGUMENT" numbered="true">
<name>ARGUMENT</name> <name>ARGUMENT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
/* /*
* Device notification types. * Device notification types.
*/ */
enum notify_deviceid_type4 { enum notify_deviceid_type4 {
NOTIFY_DEVICEID4_CHANGE = 1, NOTIFY_DEVICEID4_CHANGE = 1,
NOTIFY_DEVICEID4_DELETE = 2 NOTIFY_DEVICEID4_DELETE = 2
}; };
/* For NOTIFY4_DEVICEID4_DELETE */ /* For NOTIFY4_DEVICEID4_DELETE */
struct notify_deviceid_delete4 { struct notify_deviceid_delete4 {
skipping to change at line 42322 skipping to change at line 41537
bool ndc_immediate; bool ndc_immediate;
}; };
struct CB_NOTIFY_DEVICEID4args { struct CB_NOTIFY_DEVICEID4args {
notify4 cnda_changes<>; notify4 cnda_changes<>;
}; };
]]></sourcecode> ]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_CB_NOTIFY_DEVICEID_RESULT" numbered="true"> <section toc="exclude" anchor="OP_CB_NOTIFY_DEVICEID_RESULT" numbered="true">
<name>RESULT</name> <name>RESULT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
struct CB_NOTIFY_DEVICEID4res { struct CB_NOTIFY_DEVICEID4res {
nfsstat4 cndr_status; nfsstat4 cndr_status;
}; };
]]></sourcecode> ]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_CB_NOTIFY_DEVICEID_DESCRIPTION" numbered="true"> <section toc="exclude" anchor="OP_CB_NOTIFY_DEVICEID_DESCRIPTION" numbered="true">
<name>DESCRIPTION</name> <name>DESCRIPTION</name>
<t> <t>
The CB_NOTIFY_DEVICEID operation is used by the The CB_NOTIFY_DEVICEID operation is used by the
server to send notifications to clients about server to send notifications to clients about
skipping to change at line 42423 skipping to change at line 41638
After a server deletes a device ID, it <bcp14>MUST NOT</bcp14> After a server deletes a device ID, it <bcp14>MUST NOT</bcp14>
reuse that device ID for the same layout type until the reuse that device ID for the same layout type until the
client ID is deleted. client ID is deleted.
</t> </t>
</dd> </dd>
</dl> </dl>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007-2008) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="OP_CB_ILLEGAL" numbered="true" toc="default"> <section anchor="OP_CB_ILLEGAL" numbered="true" toc="default">
<name>Operation 10044: CB_ILLEGAL - Illegal Callback Operation</name> <name>Operation 10044: CB_ILLEGAL - Illegal Callback Operation</name>
<section toc="exclude" anchor="OP_CB_ILLEGAL_ARGUMENT" numbered="true"> <section toc="exclude" anchor="OP_CB_ILLEGAL_ARGUMENT" numbered="true">
<name>ARGUMENT</name> <name>ARGUMENT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
void; void;
]]></sourcecode> ]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_CB_ILLEGAL_RESULT" numbered="true"> <section toc="exclude" anchor="OP_CB_ILLEGAL_RESULT" numbered="true">
<name>RESULT</name> <name>RESULT</name>
<sourcecode type=""><![CDATA[ <sourcecode type="xdr"><![CDATA[
/* /*
* CB_ILLEGAL: Response for illegal operation numbers * CB_ILLEGAL: Response for illegal operation numbers
*/ */
struct CB_ILLEGAL4res { struct CB_ILLEGAL4res {
nfsstat4 status; nfsstat4 status;
}; };
]]></sourcecode> ]]></sourcecode>
</section> </section>
<section toc="exclude" anchor="OP_CB_ILLEGAL_DESCRIPTION" numbered="true"> <section toc="exclude" anchor="OP_CB_ILLEGAL_DESCRIPTION" numbered="true">
<name>DESCRIPTION</name> <name>DESCRIPTION</name>
skipping to change at line 42472 skipping to change at line 41684
A server will probably not send an operation with code A server will probably not send an operation with code
OP_CB_ILLEGAL, but if it does, the response will be CB_ILLEGAL4res OP_CB_ILLEGAL, but if it does, the response will be CB_ILLEGAL4res
just as it would be with any other invalid operation code. Note just as it would be with any other invalid operation code. Note
that if the client gets an illegal operation code that is not that if the client gets an illegal operation code that is not
OP_ILLEGAL, and if the client checks for legal operation codes OP_ILLEGAL, and if the client checks for legal operation codes
during the XDR decode phase, then an instance of during the XDR decode phase, then an instance of
data type CB_ILLEGAL4res will not be returned. data type CB_ILLEGAL4res will not be returned.
</t> </t>
</section> </section>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007) -->
<!-- Copyright (C) The Internet Society (2006) -->
</section> </section>
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007-2008) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="SECCON" numbered="true" toc="default"> <section anchor="SECCON" numbered="true" toc="default">
<name>Security Considerations</name> <name>Security Considerations</name>
<t> <t>
Historically, the authentication model of NFS Historically, the authentication model of NFS
was based on the entire machine being the NFS client, with the was based on the entire machine being the NFS client, with the
NFS server trusting the NFS client NFS server trusting the NFS client
to authenticate the end-user. to authenticate the end-user.
The NFS server in turn shared its files only to The NFS server in turn shared its files only to
specific clients, as identified by the client's source specific clients, as identified by the client's source
network address. Given this model, the AUTH_SYS network address. Given this model, the AUTH_SYS
skipping to change at line 42732 skipping to change at line 41938
</t> </t>
<t> <t>
Similar considerations apply if the threat to be avoided is the redirection Similar considerations apply if the threat to be avoided is the redirection
of client traffic to inappropriate (i.e., poorly performing) servers. In of client traffic to inappropriate (i.e., poorly performing) servers. In
both cases, there is no reason for the information returned to depend on both cases, there is no reason for the information returned to depend on
the identity of the client principal requesting it, while the validity of the the identity of the client principal requesting it, while the validity of the
server information, which has the capability to affect all client principals, server information, which has the capability to affect all client principals,
is of considerable importance. is of considerable importance.
</t> </t>
</section> </section>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007-2008) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="ianaconsider" numbered="true" toc="default"> <section anchor="ianaconsider" numbered="true" toc="default">
<name>IANA Considerations</name> <name>IANA Considerations</name>
<!-- [rfced] Section 22 (IANA Considerations) has references to
RFC 5226, which has been obsoleted by RFC 8126. May we update
the reference?
<t> <t>
This section uses terms that are defined in <xref target="RFC5226" format="default"/>. This section uses terms that are defined in <xref target="RFC8126" format="default"/>.
</t> </t>
<section anchor="Iana-actions" numbered="true" toc="default"> <section anchor="Iana-actions" numbered="true" toc="default">
<name>IANA Actions</name> <name>IANA Actions</name>
<t> <t>
This update does not require any modification of, or additions to, registry This update does not require any modification of, or additions to, registry
entries or registry rules associated with NFSv4.1. However, since entries or registry rules associated with NFSv4.1. However, since
this document obsoletes RFC 8881, IANA has updated all registry entries and registry rules references this document obsoletes RFC 5661, IANA has updated all registry entries and registry rules references
that point to RFC 5661 to point to this document instead. that point to RFC 5661 to point to this document instead.
</t> </t>
<t> <t>
Previous actions by IANA related to NFSv4.1 are listed in the remaining Previous actions by IANA related to NFSv4.1 are listed in the remaining
subsections of <xref target="ianaconsider" format="default"/>. subsections of <xref target="ianaconsider" format="default"/>.
</t> </t>
</section> </section>
<section anchor="namedattributesiana" numbered="true" toc="default"> <section anchor="namedattributesiana" numbered="true" toc="default">
<name>Named Attribute Definitions</name> <name>Named Attribute Definitions</name>
<t> <t>
skipping to change at line 42780 skipping to change at line 41979
attributes as needed, they are encouraged to register the attributes as needed, they are encouraged to register the
attributes with IANA. attributes with IANA.
</t> </t>
<t> <t>
Such registered named attributes are presumed to apply to all minor Such registered named attributes are presumed to apply to all minor
versions of NFSv4, including those defined subsequently to the versions of NFSv4, including those defined subsequently to the
registration. If the named attribute is intended to be registration. If the named attribute is intended to be
limited to specific minor versions, this will be clearly stated in limited to specific minor versions, this will be clearly stated in
the registry's assignment. the registry's assignment.
</t> </t>
<!-- [IANA] If we can update RFC 5226 to RFC 8126, the following xrefs change:
Current:
All assignments to the registry are made on a First Come First Served basis,
per <xref target="RFC5226" sectionFormat="of" section="4.1"/>.
The policy for each assignment is Specification Required,
per <xref target="RFC5226" sectionFormat="of" section="4.1"/>.
Updated:
All assignments to the registry are made on a First Come First Served basis,
per <xref target="RFC81216" sectionFormat="of" section="4.4"/>.
The policy for each assignment is Specification Required,
per <xref target="RFC8126" sectionFormat="of" section="4.6"/>.
<t> <t>
All assignments to the registry are made on a First Come First Served basis, All assignments to the registry are made on a First Come First Served basis,
per <xref target="RFC5226" sectionFormat="of" section="4.1"/>. per <xref target="RFC8126" sectionFormat="of" section="4.4"/>.
The policy for each assignment is Specification Required, The policy for each assignment is Specification Required,
per <xref target="RFC5226" sectionFormat="of" section="4.1"/>. per <xref target="RFC8126" sectionFormat="of" section="4.6"/>.
</t> </t>
<t> <t>
Under the NFSv4.1 specification, the name of a named Under the NFSv4.1 specification, the name of a named
attribute can in theory be up to 2<sup>32</sup> - 1 bytes in attribute can in theory be up to 2<sup>32</sup> - 1 bytes in
length, but in practice NFSv4.1 clients and servers length, but in practice NFSv4.1 clients and servers
will be unable to handle a string that long. IANA will be unable to handle a string that long. IANA
should reject any assignment request with a named should reject any assignment request with a named
attribute that exceeds 128 UTF-8 characters. To give the attribute that exceeds 128 UTF-8 characters. To give the
IESG the flexibility to set up bases of assignment of IESG the flexibility to set up bases of assignment of
Experimental Use and Standards Action, Experimental Use and Standards Action,
skipping to change at line 42888 skipping to change at line 42070
The potential exists for new notification types to be The potential exists for new notification types to be
added to the CB_NOTIFY_DEVICEID operation (see <xref target="OP_CB_NOTIFY_DEVICEID" format="default"/>). This can be done added to the CB_NOTIFY_DEVICEID operation (see <xref target="OP_CB_NOTIFY_DEVICEID" format="default"/>). This can be done
via changes to the operations that register via changes to the operations that register
notifications, or by adding new operations to NFSv4. notifications, or by adding new operations to NFSv4.
This requires a new minor version of NFSv4, and This requires a new minor version of NFSv4, and
requires a Standards Track document from the IETF. requires a Standards Track document from the IETF.
Another way to add a notification is to specify a new Another way to add a notification is to specify a new
layout type (see <xref target="pnfsiana" format="default"/>). layout type (see <xref target="pnfsiana" format="default"/>).
</t> </t>
<!-- [IANA] If we update the IANA Guidelines ref.
Current:
Hence, all assignments to the registry are made on a Standards Action
basis per <xref target="RFC5226" section="4.1" sectionFormat="of" format="default"/>, with
Expert Review required.
Updated:
Hence, all assignments to the registry are made on a Standards Action
basis per <xref target="RFC8126" section="4.6" sectionFormat="of" format="default"/>, with
Expert Review required.
<t> <t>
Hence, all assignments to the registry are made on a Standards Action Hence, all assignments to the registry are made on a Standards Action
basis per <xref target="RFC5226" section="4.1" sectionFormat="of" format="default"/>, with basis per <xref target="RFC8126" section="4.6" sectionFormat="of" format="default"/>, with
Expert Review required. Expert Review required.
</t> </t>
<t> <t>
The registry is a list of assignments, each containing The registry is a list of assignments, each containing
five fields per assignment. five fields per assignment.
</t> </t>
<ol spacing="normal" type="1"> <ol spacing="normal" type="1">
<li> <li>
The name of the notification type. This name must have the The name of the notification type. This name must have the
skipping to change at line 43010 skipping to change at line 42180
IANA created a registry called the "NFSv4 Recallable Object Types Registry". IANA created a registry called the "NFSv4 Recallable Object Types Registry".
</t> </t>
<t> <t>
The potential exists for new object types to be added to the CB_RECALL_ANY operation (see The potential exists for new object types to be added to the CB_RECALL_ANY operation (see
<xref target="OP_CB_RECALL_ANY" format="default"/>). This can be done via changes to <xref target="OP_CB_RECALL_ANY" format="default"/>). This can be done via changes to
the operations that add recallable types, or by adding new operations the operations that add recallable types, or by adding new operations
to NFSv4. This requires a new minor version of NFSv4, and requires to NFSv4. This requires a new minor version of NFSv4, and requires
a Standards Track document from IETF. Another way to a Standards Track document from IETF. Another way to
add a new recallable object is to specify a new layout type (see <xref target="pnfsiana" format="default"/>). add a new recallable object is to specify a new layout type (see <xref target="pnfsiana" format="default"/>).
</t> </t>
<!-- [IANA] If we update the IANA Guidelines ref:
Current:
All assignments to the registry are made on a Standards Action
basis per <xref target="RFC5226" sectionFormat="of" section="4.1"/>, with
Expert Review required.
Updated:
All assignments to the registry are made on a Standards Action
basis per <xref target="RFC8126" sectionFormat="of" section="4.9"/>, with
Expert Review required.
<t> <t>
All assignments to the registry are made on a Standards Action All assignments to the registry are made on a Standards Action
basis per <xref target="RFC5226" sectionFormat="of" section="4.1"/>, with basis per <xref target="RFC8126" sectionFormat="of" section="4.9"/>, with
Expert Review required. Expert Review required.
</t> </t>
<t> <t>
Recallable object types are 32-bit unsigned numbers. There are no Reserved Recallable object types are 32-bit unsigned numbers. There are no Reserved
values. Values in the range 12 through 15, inclusive, are designated for Private values. Values in the range 12 through 15, inclusive, are designated for Private
Use. Use.
</t> </t>
<t> <t>
The registry is a list of assignments, each containing The registry is a list of assignments, each containing
five fields per assignment. five fields per assignment.
skipping to change at line 43374 skipping to change at line 42532
</li> </li>
</ul> </ul>
</li> </li>
<li> <li>
The author documents the new layout specification as an Internet-Draft. The author documents the new layout specification as an Internet-Draft.
</li> </li>
<li> <li>
The author submits the Internet-Draft for review through the The author submits the Internet-Draft for review through the
IETF standards process as defined in "The Internet Standards IETF standards process as defined in "The Internet Standards
Process--Revision 3" (BCP 9). Process--Revision 3" (BCP 9 <xref target="BCP09" format="default"/>).
The new layout specification will be The new layout specification will be
submitted for eventual publication as a Standards Track RFC. submitted for eventual publication as a Standards Track RFC.
</li> </li>
<li> <li>
The layout specification progresses through the IETF standards The layout specification progresses through the IETF standards
process. process.
</li> </li>
</ol> </ol>
</section> </section>
</section> </section>
skipping to change at line 43631 skipping to change at line 42789
<section numbered="true" toc="default"> <section numbered="true" toc="default">
<name>Updating Registrations</name> <name>Updating Registrations</name>
<t> <t>
The registrant is free to update the assignment, i.e., change the The registrant is free to update the assignment, i.e., change the
explanation and/or point of contact fields. explanation and/or point of contact fields.
</t> </t>
</section> </section>
</section> </section>
</section> </section>
</section> </section>
<!--[auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007) -->
<!-- Copyright (C) The Internet Society (2006) -->
</middle> </middle>
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007) -->
<!-- Copyright (C) The Internet Society (2006) -->
<back> <back>
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007-2008) -->
<!-- Copyright (C) The Internet Society (2006) -->
<references> <references>
<name>References</name> <name>References</name>
<references> <references>
<name>Normative References</name> <name>Normative References</name>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.4506.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.4506.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5531.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5531.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2203.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2203.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.4121.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.4121.xml"/>
<!-- [rfced] Please note that we have moved the ISBN info to the <seriesInfo>
element. While we would normally make other changes to the Open Group
references, we have not made them because these appear in RFC 5661.
For example, Original:
[6] The Open Group, "Section 3.191 of Chapter 3 of Base
Definitions of The Open Group Base Specifications Issue 6
IEEE Std 1003.1, 2004 Edition, HTML Version
(www.opengroup.org), ISBN 1931624232", 2004.
Current:
[6] The Open Group, "Section 3.191 of Chapter 3 of Base
Definitions of The Open Group Base Specifications Issue 6
IEEE Std 1003.1, 2004 Edition, HTML Version",
ISBN 1931624232, 2004, <https://www.opengroup.org>.
<reference anchor="hardlink" target="https://www.opengroup.org"> <reference anchor="hardlink" target="https://www.opengroup.org">
<front> <front>
<title abbrev="Open Group">Section 3.191 of Chapter 3 of <title abbrev="Open Group">Section 3.191 of Chapter 3 of
Base Definitions of The Open Group Base Specifications Issue 6 Base Definitions of The Open Group Base Specifications Issue 6
IEEE Std 1003.1, 2004 Edition, HTML Version </title> IEEE Std 1003.1, 2004 Edition, HTML Version </title>
<seriesInfo name="ISBN" value="1931624232"/> <seriesInfo name="ISBN" value="1931624232"/>
<author> <author>
<organization>The Open Group </organization> <organization>The Open Group </organization>
</author> </author>
<date year="2004"/> <date year="2004"/>
skipping to change at line 43825 skipping to change at line 42957
<title>Section 'unlink()' of <title>Section 'unlink()' of
System Interfaces of The Open Group Base Specifications Issue 6 System Interfaces of The Open Group Base Specifications Issue 6
IEEE Std 1003.1, 2004 Edition, HTML Version </title> IEEE Std 1003.1, 2004 Edition, HTML Version </title>
<seriesInfo name="ISBN" value="1931624232"/> <seriesInfo name="ISBN" value="1931624232"/>
<author> <author>
<organization>The Open Group </organization> <organization>The Open Group </organization>
</author> </author>
<date year="2004"/> <date year="2004"/>
</front> </front>
</reference> </reference>
<!-- [auth] obsoleted by RFC 5531
<reference anchor='RFC1831'>
<front>
<title abbrev='Remote Procedure Call Protocol Version 2'>RPC:
Remote Procedure Call Protocol Specification Version 2</title>
<author initials='R.' surname='Srinivasan' fullname='Raj Srinivasan'>
<organization>Sun Microsystems, Inc., ONC Technologies</organization>
<address>
<postal>
<street>2550 Garcia Avenue</street>
<street>M/S MTV-5-40</street>
<city>Mountain View</city>
<region>CA</region>
<code>94043</code>
<country>US</country></postal>
<phone>+1 415 336 2478</phone>
<facsimile>+1 415 336 6015</facsimile>
<email>raj@eng.sun.com</email></address></author>
<date year='1995' month='August' />
<abstract>
<t>This document describes the ONC Remote Procedure Call (ONC
RPC Version 2) protocol as it is currently deployed and
accepted. "ONC" stands for "Open Network
Computing".</t></abstract></front>
<seriesInfo name='RFC' value='1831' />
<format type='TXT' octets='37798' target='ftp://ftp.isi.edu/in-notes/rfc1831.txt' />
</reference> -->
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.4055.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.4055.xml"/>
<reference anchor="CSOR_AES" target="http://csrc.nist.gov/groups/ST/crypto_apps_infra/csor/algorithms.html"> <reference anchor="CSOR_AES" target="https://csrc.nist.gov/projects/computer-security-objects-register/algorithm-registration">
<front> <front>
<title>Cryptographic Algorithm Object Registration <title>Computer Security Objects Register
</title> </title>
<author> <author>
<organization>National Institute of Standards and Technology <organization>National Institute of Standards and Technology
</organization> </organization>
</author> </author>
<date month="November" year="2007"/> <date month="May" year="2016"/>
</front> </front>
</reference> </reference>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7861.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7861.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.4120.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.4120.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.4033.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.4033.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7858.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7858.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8000.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8000.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8166.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8166.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8267.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8267.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8484.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8484.xml"/>
<!-- Add this ref if we can add a reference to BCP 9 (mentioned in the IC section):
<referencegroup anchor="BCP09" target="https://www.rfc-editor.org/info/bcp9"> <referencegroup anchor="BCP09" target="https://www.rfc-editor.org/info/bcp9">
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2026.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2026.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7127.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7127.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5657.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5657.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.6410.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.6410.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7100.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7100.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7475.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7475.xml"/>
</referencegroup> </referencegroup>
</references> </references>
<references> <references>
<name>Informative References</name> <name>Informative References</name>
<!--draft-roach-bis-documents expired -->
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml3/reference.I-D.draft-roach-bis-documents-00.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml3/reference.I-D.draft-roach-bis-documents-00.xml"/>
<!-- RFC 3530 (NFSv4 version 0) is obsoleted by RFC 7530, but is
mentioned in historical context.
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.3530.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.3530.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.1813.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.1813.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2847.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2847.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2623.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2623.xml"/>
<reference anchor="Chet"> <reference anchor="Chet">
<front> <front>
<title>Improving the Performance <title>Improving the Performance
and Correctness of an NFS Server</title> and Correctness of an NFS Server</title>
<author initials="C." surname="Juszczak" fullname="Chet Juszczak"> <author initials="C." surname="Juszczak" fullname="Chet Juszczak">
skipping to change at line 43948 skipping to change at line 43044
The presentation provides implementation advice for The presentation provides implementation advice for
ONC RPC transaction identifier (xid) generation. ONC RPC transaction identifier (xid) generation.
</t> </t>
</abstract> </abstract>
</front> </front>
<refcontent>USENIX Conference Proceedings</refcontent> <refcontent>USENIX Conference Proceedings</refcontent>
</reference> </reference>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.1094.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.1094.xml"/>
<!-- Found the following
http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.33.7106&rep=rep1&type=pdf
<reference anchor="ha_nfs_ibm"> <reference anchor="ha_nfs_ibm">
<front> <front>
<title>A Highly Available Network Server</title> <title>A Highly Available Network Server</title>
<author initials="A." surname="Bhide" fullname="Anupam Bhide"> <author initials="A." surname="Bhide" fullname="Anupam Bhide">
<organization>IBM T.J. Watson Research Center</organization> <organization>IBM T.J. Watson Research Center</organization>
</author> </author>
<author initials="E. N." surname="Elnozahy" fullname="Elmootazbellah N. Elnozahy"> <author initials="E. N." surname="Elnozahy" fullname="Elmootazbellah N. Elnozahy">
<organization>IBM T.J. Watson Research Center</organization> <organization>IBM T.J. Watson Research Center</organization>
</author> </author>
<author initials="S. P." surname="Morgan" fullname="Stephen P. Morgan "> <author initials="S. P." surname="Morgan" fullname="Stephen P. Morgan ">
skipping to change at line 43996 skipping to change at line 43089
</abstract> </abstract>
</front> </front>
<refcontent>USENIX Conference Proceedings</refcontent> <refcontent>USENIX Conference Proceedings</refcontent>
</reference> </reference>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5664.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5664.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5663.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5663.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2054.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2054.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2055.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2055.xml"/>
<!-- [rfced] The original URL no longer works; we have updated the URL
accordingly. Please let us know if you have any concerns.
Original:
http://www.ietf.org/IESG/STATEMENTS/iesg-statement-07-30-2008.txt
Current:
https://www.ietf.org/about/groups/iesg/statements/processing-rfc-errata/
<reference anchor="errata" target="https://www.ietf.org/about/groups/iesg/statements/processing-rfc-errata/"> <reference anchor="errata" target="https://www.ietf.org/about/groups/iesg/statements/processing-rfc-errata/">
<front> <front>
<title>IESG Processing of RFC Errata for the IETF Stream <title>IESG Processing of RFC Errata for the IETF Stream
</title> </title>
<author> <author>
<organization>IESG <organization>IESG
</organization> </organization>
</author> </author>
<date month="July" year="2008"/> <date month="July" year="2008"/>
</front> </front>
skipping to change at line 44045 skipping to change at line 43129
<organization/> <organization/>
</author> </author>
<author initials="V." surname="Jacobson"> <author initials="V." surname="Jacobson">
<organization/> <organization/>
</author> </author>
<date month="April" year="1994"/> <date month="April" year="1994"/>
</front> </front>
<refcontent>IEEE/ACM Transactions on Networking, 2(2), pp. 122-136</refcontent> <refcontent>IEEE/ACM Transactions on Networking, 2(2), pp. 122-136</refcontent>
</reference> </reference>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.3720.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7143.xml"/>
<reference anchor="FCP-2"> <reference anchor="FCP-2">
<front> <front>
<title>Fibre Channel Protocol for SCSI, 2nd Version (FCP-2)</title> <title>Fibre Channel Protocol for SCSI, 2nd Version (FCP-2)</title>
<author initials="R." surname="Snively" fullname="Robert Snively"> <author initials="R." surname="Snively" fullname="Robert Snively">
<organization>Brocade Communication Systems, Inc.</organization> <organization>Brocade Communication Systems, Inc.</organization>
</author> </author>
<date month="Oct" year="2003"/> <date month="Oct" year="2003"/>
</front> </front>
<refcontent>ANSI/INCITS, 350-2003</refcontent> <refcontent>ANSI/INCITS, 350-2003</refcontent>
</reference> </reference>
<!-- [rfced] The URL http://www.t10.org/ftp/t10/drafts/osd/osd-r10.pdf <reference anchor="OSD-T10" target="https://www.t10.org/drafts.htm">
does not work. Should the URL be removed or updated?
Original:
[57] Weber, R., "Object-Based Storage Device Commands (OSD)",
ANSI/INCITS 400-2004, July 2004,
<http://www.t10.org/ftp/t10/drafts/osd/osd-r10.pdf>.
<reference anchor="OSD-T10" target="http://www.t10.org/ftp/t10/drafts/osd/osd-r10.pdf">
<front> <front>
<title>Object-Based Storage Device Commands (OSD)</title> <title>Object-Based Storage Device Commands (OSD)</title>
<author initials="R.O." surname="Weber" fullname="Ralph O. Weber"> <author initials="R.O." surname="Weber" fullname="Ralph O. Weber">
<organization>ENDL Texas</organization> <organization>ENDL Texas</organization>
</author> </author>
<date month="July" year="2004"/> <date month="July" year="2004"/>
</front> </front>
<refcontent>ANSI/INCITS, 400-2004</refcontent> <refcontent>ANSI/INCITS, 400-2004</refcontent>
</reference> </reference>
skipping to change at line 44120 skipping to change at line 43196
<abstract> <abstract>
<t> <t>
The description of the access() function states: "If the process has appropriate privileges, an implementation may indicate success for X_OK even if none of the execute file permission bits are set." The description of the access() function states: "If the process has appropriate privileges, an implementation may indicate success for X_OK even if none of the execute file permission bits are set."
</t> </t>
</abstract> </abstract>
</front> </front>
</reference> </reference>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2224.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2224.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2755.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2755.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5226.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8126.xml"/>
<reference anchor="Err2006" quote-title="false" target="https://www.rfc-editor.org/errata/eid2006"> <reference anchor="Err2006" quote-title="false" target="https://www.rfc-editor.org/errata/eid2006">
<front> <front>
<title>Erratum ID 2006</title> <title>Erratum ID 2006</title>
<author> <author>
<organization>RFC Errata</organization> <organization>RFC Errata</organization>
</author> </author>
</front> </front>
<refcontent>RFC 5661</refcontent> <refcontent>RFC 5661</refcontent>
</reference> </reference>
<!-- [rfced] This URL appears to refer to a personal site. Is there a <reference anchor="AFS">
stable URL to which we can refer?
Original:
[64] Spasojevic, M. and M. Satayanarayanan, "An Empirical Study
of a Wide-Area Distributed File System", May 1996,
<https://www.cs.cmu.edu/~satya/docdir/spasojevic-tocs-afs-
measurement-1996.pdf>.
<reference anchor="AFS" target="https://www.cs.cmu.edu/~satya/docdir/spasojevic-tocs-afs-measurement-1996.pdf">
<front> <front>
<title> <title>
An Empirical Study of a Wide-Area Distributed File System An Empirical Study of a Wide-Area Distributed File System
</title> </title>
<author initials="M." surname="Spasojevic" fullname="Mirjana Spasojevic"> <author initials="M." surname="Spasojevic" fullname="Mirjana Spasojevic">
</author> </author>
<author initials="M." surname="Satayanarayanan" fullname="Mahadev Satayanarayanan"> <author initials="M." surname="Satayanarayanan" fullname="Mahadev Satayanarayanan">
</author> </author>
<date year="1996" month="May"/> <date year="1996" month="May"/>
</front> </front>
<refcontent>ACM Transactions on Computer Systems</refcontent>
<refcontent>Vol. 14</refcontent>
<refcontent>No. 2</refcontent>
<refcontent>pp. 200-222</refcontent>
<seriesInfo name="DOI" value="10.1145/227695.227698"/>
</reference> </reference>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5661.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5661.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8178.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8178.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7530.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7530.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7931.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7931.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8434.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8434.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7258.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7258.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.3552.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.3552.xml"/>
</references> </references>
</references> </references>
<!-- [auth] $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ -->
<!-- Copyright (C) The IETF Trust (2007-2008) -->
<!-- Copyright (C) The Internet Society (2006) -->
<section anchor="NEED" numbered="true" toc="default"> <section anchor="NEED" numbered="true" toc="default">
<name>The Need for This Update</name> <name>The Need for This Update</name>
<t> <t>
This document includes an explanation of how clients and servers This document includes an explanation of how clients and servers
are to determine the particular network access paths to be used to access a are to determine the particular network access paths to be used to access a
file system. This includes descriptions of file system. This includes descriptions of
how to handle changes to the specific replica to be used or to how to handle changes to the specific replica to be used or to
the set of addresses to be used to access it, the set of addresses to be used to access it,
and how to deal transparently with transfers of responsibility that need to be and how to deal transparently with transfers of responsibility that need to be
made. This includes cases in which made. This includes cases in which
skipping to change at line 44408 skipping to change at line 43477
subsections. subsections.
</li> </li>
<li> <li>
<xref target="SEC11-USES-mult" format="default"/> <xref target="SEC11-USES-mult" format="default"/>
is the new first subsection of the overall section. is the new first subsection of the overall section.
</li> </li>
<li> <li>
<xref target="SEC11-USES-trunk" format="default"/> <xref target="SEC11-USES-trunk" format="default"/>
is the new second subsection of the overall section. is the new second subsection of the overall section.
</li> </li>
<!-- [rfced] In Section B.1.1, we're not sure what 11.4.4 and 11.4.5 refer to
in the following sentence. Is there a missing bullet point?
Current:
Each of the Sections 11.5.4, 11.5.5, and 11.5.6
replaces (in order) one of the corresponding
Sections 11.4.1, 11.4.2, and 11.4.3 of RFC 5661 [66].
11.4.4, and 11.4.5.
-->
<li> <li>
Each of the Sections Each of the Sections
<xref target="SEC11-USES-repl" format="counter"/>, <xref target="SEC11-USES-repl" format="counter"/>,
<xref target="SEC11-USES-migr" format="counter"/>, and <xref target="SEC11-USES-migr" format="counter"/>, and
<xref target="SEC11-USES-ref" format="counter"/> <xref target="SEC11-USES-ref" format="counter"/>
replaces (in order) one of the corresponding Sections replaces (in order) one of the corresponding Sections
<xref target="RFC5661" sectionFormat="bare" section="11.4.1"/>, <xref target="RFC5661" sectionFormat="bare" section="11.4.1"/>,
<xref target="RFC5661" sectionFormat="bare" section="11.4.2"/>, and <xref target="RFC5661" sectionFormat="bare" section="11.4.2"/>, and
<xref target="RFC5661" sectionFormat="bare" section="11.4.3"/> of RFC 5661 <xref target="RFC5661" sectionFormat="bare" section="11.4.3"/> of RFC 5661
<xref target="RFC5661"/>. <xref target="RFC5661"/>.
11.4.4, and 11.4.5.
</li> </li>
<li> <li>
<xref target="SEC11-USES-changes" format="default"/> <xref target="SEC11-USES-changes" format="default"/>
is the new final subsection of the overall section. is the new final subsection of the overall section.
</li> </li>
</ul> </ul>
</section> </section>
<section anchor="SEC11-trans-reorg" toc="exclude" numbered="true"> <section anchor="SEC11-trans-reorg" toc="exclude" numbered="true">
<name>Reorganization of Material Dealing with File System Transitions</name> <name>Reorganization of Material Dealing with File System Transitions</name>
<t> <t>
skipping to change at line 44665 skipping to change at line 43724
occurring on a single network address. occurring on a single network address.
</li> </li>
</ul> </ul>
<t> <t>
As these assumptions have become invalid in the context of As these assumptions have become invalid in the context of
Transparent State Migration and active use of trunking, Transparent State Migration and active use of trunking,
the treatment has been modified in several respects: the treatment has been modified in several respects:
</t> </t>
<ul spacing="normal"> <ul spacing="normal">
<li> <li>
<!-- [rfced] We are having difficulty parsing the following sentence <t>
in Appendix B.2.1.
Current:
It had been assumed that an EXCHANGE_ID executed when the server
is already aware of a given client instance must be either updating
associated parameters (e.g., with respect to callbacks) or a
lingering retransmission to deal with a previously lost reply.
Perhaps:
It had been assumed that an EXCHANGE_ID executed when the server It had been assumed that an EXCHANGE_ID executed when the server
was already aware that a given client instance was either updating was already aware that a given client instance was either updating
associated parameters (e.g., with respect to callbacks) or dealing associated parameters (e.g., with respect to callbacks) or dealing
with a previously lost reply by retransmitting. with a previously lost reply by retransmitting. As a
<t>
It had been assumed that an EXCHANGE_ID executed when the server
is already aware of a
given client instance must be either updating associated
parameters (e.g., with respect to callbacks) or a lingering
retransmission to deal with a previously lost reply. As
result, any slot sequence returned by that operation result, any slot sequence returned by that operation
would be of no use. The original treatment would be of no use. The original treatment
went so far as to say that it "<bcp14>MUST NOT</bcp14>" be used, although went so far as to say that it "<bcp14>MUST NOT</bcp14>" be used, although
this usage was not in accord with <xref target="RFC2119" format="default"/>. this usage was not in accord with <xref target="RFC2119" format="default"/>.
This created a difficulty when an EXCHANGE_ID is done after Transparent State This created a difficulty when an EXCHANGE_ID is done after Transparent State
Migration since that slot sequence would need to be used in a Migration since that slot sequence would need to be used in a
subsequent CREATE_SESSION. subsequent CREATE_SESSION.
</t> </t>
<t> <t>
In the updated treatment, CREATE_SESSION is a way that client In the updated treatment, CREATE_SESSION is a way that client
skipping to change at line 44710 skipping to change at line 43753
</li> </li>
<li> <li>
<t> <t>
It had been assumed that the only functions of EXCHANGE_ID were to It had been assumed that the only functions of EXCHANGE_ID were to
inform the server of the client, to create the client ID, inform the server of the client, to create the client ID,
and to communicate it to the client. When multiple and to communicate it to the client. When multiple
simultaneous connections are involved, as often happens when simultaneous connections are involved, as often happens when
trunking, that treatment was inadequate in that it ignored the trunking, that treatment was inadequate in that it ignored the
role of EXCHANGE_ID in associating the client ID with the role of EXCHANGE_ID in associating the client ID with the
connection on which it was done, so that it could be used connection on which it was done, so that it could be used
by a subsequent CREATE_SESSSION whose parameters do not by a subsequent CREATE_SESSION whose parameters do not
include an explicit client ID. include an explicit client ID.
</t> </t>
<t> <t>
The new treatment explicitly discusses the role of EXCHANGE_ID The new treatment explicitly discusses the role of EXCHANGE_ID
in associating the client ID with the connection so it in associating the client ID with the connection so it
can be used by CREATE_SESSION and in associating a connection with an can be used by CREATE_SESSION and in associating a connection with an
existing session. existing session.
</t> </t>
</li> </li>
</ul> </ul>
skipping to change at line 44796 skipping to change at line 43839
<xref target="RFC5661" sectionFormat="bare" section="15"/> of RFC 5661 <xref target="RFC5661" sectionFormat="bare" section="15"/> of RFC 5661
<xref target="RFC5661"/> <xref target="RFC5661"/>
so that the text applies properly to reclaims for all types of grace so that the text applies properly to reclaims for all types of grace
periods. The updated descriptions periods. The updated descriptions
appear within <xref target="errors_reclaim" format="default"/>. appear within <xref target="errors_reclaim" format="default"/>.
</li> </li>
<li> <li>
Because of the need to provide the clarifications in errata Because of the need to provide the clarifications in errata
report 2006 <xref target="Err2006" format="default"/> report 2006 <xref target="Err2006" format="default"/>
and to adapt these to properly explain the interaction of and to adapt these to properly explain the interaction of
NFS4ERR_DELAY with the replay cache, a revised description NFS4ERR_DELAY with the reply cache, a revised description
of NFS4ERR_DELAY appears in <xref target="err_DELAY" format="default"/>. This of NFS4ERR_DELAY appears in <xref target="err_DELAY" format="default"/>. This
errata report, unlike many other RFC 5661 errata reports, is errata report, unlike many other RFC 5661 errata reports, is
addressed in this addressed in this
document because of the extensive use of NFS4ERR_DELAY document because of the extensive use of NFS4ERR_DELAY
in connection with state migration and session migration. in connection with state migration and session migration.
</li> </li>
</ul> </ul>
</section> </section>
<section anchor="CHG-other" numbered="true" toc="default"> <section anchor="CHG-other" numbered="true" toc="default">
<name>Other Revisions Made to RFC 5661</name> <name>Other Revisions Made to RFC 5661</name>
 End of changes. 541 change blocks. 
1253 lines changed or deleted 336 lines changed or added

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